Objects API¶
Status: experimental authenticated workspace API
The kernel object engine (ADR 0015) lets workspace administrators define
objects and fields at runtime and lets members work with their records. Every
route sits beneath /api/v1/workspaces/{workspace_id}/objects, requires an
active membership, and returns 404 when the workspace, object or record must
be concealed.
Naming¶
API names are namespace:name. Everything a workspace administrator defines
lives in the custom namespace (custom:project, custom:status); plugin
objects and fields use the plugin id (example.loyalty:tier). Requests take
the short name and the engine qualifies it. Names are a lowercase letter
followed by lowercase letters, digits or single underscores, at most 63
characters. Dots are reserved for relationship traversal in the query
language.
Every object has a three-character key prefix that starts every record id.
Workspace objects always get a digit-first prefix (000, 001, ...); plugin
prefixes start with a letter, so the two never collide. Each definition also
carries an explicit origin (system, plugin or workspace).
In the query language and in formulas a dotted plugin namespace directly
followed by : is one name, so example.tracker:milestone.name traverses
the plugin lookup example.tracker:milestone.
Authorisation¶
| Operations | Required access |
|---|---|
| Create, change and delete objects and fields; read and set object permissions; change the record draft expiry | objects.manage |
| Read the record draft settings | any member |
| See an object and read its records | object read |
| Create records | object create |
| Change, archive and unarchive records | object edit, and edit access to the record |
| Delete and undelete records | object delete |
| Read or change every record whatever sharing says | object view_all / modify_all, or the system permissions records.view_all / records.modify_all |
Object permissions are granted per role. A stronger grant implies the weaker
ones: modify_all implies view_all and delete, delete implies edit,
and every grant implies read. An object the caller cannot read is reported as 404, exactly
like a missing one; an operation the caller may not perform on an object they
can read returns 403 auth.permission_denied.
Objects and fields¶
| Method and path | Purpose |
|---|---|
GET /objects |
Objects the caller can read, with their effective access, plus can_manage |
POST /objects |
Create an object: name, label, plural_label, optional description, name_label, sharing_model (private, read, read_write), grant_hierarchy, searchable, in_navigation |
GET /objects/{api_name} |
Describe an object with its active fields in order |
PATCH /objects/{api_name} |
Change labels and settings, including path_field; send expected_version |
DELETE /objects/{api_name}?expected_version= |
Delete an object; refused with 409 objects.object_referenced while lookups, or related-to fields that allow nothing else, point to it, and 409 objects.object_in_use while an automation creates its records |
POST /objects/{api_name}/fields |
Create a field |
PATCH /objects/{api_name}/fields/{field} |
Change a field; send expected_version |
DELETE /objects/{api_name}/fields/{field}?expected_version= |
Retire a field; its values disappear from records |
GET /objects/{api_name}/permissions |
Every workspace role with its access to the object |
PUT /objects/{api_name}/permissions/{role_id} |
Set a role's access: read, create, edit, delete, view_all, modify_all |
GET /field-permissions |
The permissions a field may name, with their descriptions, for the Object Manager's pickers; needs objects.manage |
Field types are text, long_text, email, phone, url, number,
currency, percent, boolean, date, date_time, picklist,
multi_picklist, lookup, formula, master_detail, rollup and
related_to. A field may be required, unique (text,
email, phone, URL and number types; case-insensitive), indexed (for filters
and sorting) and searchable. Text fields take a max_length from 1 to
255 (255 by default), long text from 1 to 131,072, and email fields from 1
to 320, for the longest addresses mail allows (255 by default; ADR 0035 G8);
it can be raised later. An email's local part has at most 64 characters and
its domain at most 255. Picklists take options with value, label,
active, default, outcome and weight (see Paths below). Lookups take reference_object and a
delete_behaviour of clear (the default) or restrict. A field's type,
uniqueness and lookup target cannot change once it exists.
A master_detail field (ADR 0025) is a lookup to the record's master. It
takes reference_object, is always required, and has no delete behaviour,
default or uniqueness. Only an object without records can get one, an object
has at most two (two make a junction object), and masters cannot themselves
be details: creating one otherwise fails with objects.master_detail_invalid,
409 objects.master_detail_limit_reached or
409 objects.master_detail_has_records. Turning required off fails with
objects.master_detail_settings_invalid.
A rollup field (ADR 0026) summarises the master's detail records. It takes
rollup with function (count, sum, min or max), object (the
detail object), relationship (its master-detail field pointing here) and,
for anything but a count, field (the detail field to summarise: a number,
currency or percent field, or for a minimum or maximum also a date or
date-time). Creating one fails with:
- objects.rollup_object_unknown;
- objects.rollup_relationship_invalid;
- objects.rollup_field_required, objects.rollup_field_not_allowed or
objects.rollup_field_invalid;
- 409 objects.rollup_limit_reached beyond 25 roll-ups on an object.
The result type is in formula_type. The summarised field is indexed if it
was not, and turning its index off fails with objects.rollup_needs_index.
Deleting the summarised field, the master-detail field or the detail object
fails with 409 objects.field_in_use or objects.object_in_use.
Field permissions¶
A field may name a read_permission and a write_permission (G5 of
ADR 0035): permission ids from the workspace's catalog, such as
contacts.people.custom-fields.read. Administrators with objects.manage
set them on workspace fields with POST .../fields and
PATCH .../fields/{field} (null removes one); a plugin declares them on
its own fields in its manifest, and administrators cannot change those
(409 objects.plugin_owned). A malformed id fails with
objects.field_permission_invalid, and one the catalog does not hold with
objects.field_permission_unknown. Formula and roll-up summary fields take
a read permission only. The settings are metadata: changing them moves the
workspace metadata version, and device replicas take them with the rest of
the definition.
A member without a field's read permission never sees the field:
GET /objects/{api_name}leaves it out; administrators withobjects.managesee every field, each with the caller'saccess({"read": …, "edit": …});- records, lists, composite results and device sync never carry its value;
- the query language, list filters and reports treat it as a field the
object does not have (
query.field_unknown,records.field_unknown): it cannot be selected, filtered, sorted or grouped on, also across a relationship, so a shared report that names one fails for that member; - search never matches a field with a read permission, for anyone, and results show only fields the caller reads;
- history entries for it are left out, and change log entries do not name it (an entry whose changes were all to hidden fields stays, naming none, because the record's version moved);
- related lists through it and timeline sources that need it are left out;
- quick actions that preset it, or a create action whose reference field
it is, are left out of
GET .../quick-actions(and so of device replicas) and of the timeline's actions, as are those that preset a field the member reads but may not change: a member is offered only actions they can complete. Administrators withobjects.managelist every action to maintain it; the save stays refused for anyone; - a formula field that reads it, on the record, through a lookup or through another formula field, and a roll-up summary of it, are hidden too. Formulas and roll-ups are computed with full access and hidden whenever they depend on a field the member cannot read, so they never leak one.
Writing needs reading: a write that names a field the caller cannot read
fails with records.field_unknown, before its value is looked at. A
member who reads a field but lacks its write permission gets
403 records.field_not_writable, with an errors entry for each such
field, when a create gives it a value or an update changes it; an update
that sends its current value, and a create that leaves it to its default,
succeed.
The check is one engine function (FieldSecurity::field), applied to
every request as the member, on the server and in a device's replica.
System context bypasses it, as it bypasses sharing: the kernel, a plugin's
installation, the migrator (G4, when it lands), automations, validation rules, lookup filters
and roll-up summaries kept current read and write every field. Member permissions
never bypass it: records.view_all and records.modify_all widen record
access, not field access. Role-based field-level security (#316) is a
follow-up that extends the same function.
Paths and outcomes¶
A picklist option may carry an outcome (ADR 0037 §1): open, the default,
positive or negative. A value other than open closes the record: the
record page's path groups it last and the board hides it unless asked. Only
a single-value picklist's options may have an outcome; a multi-select
picklist's answer 400 objects.options_invalid. An option may also carry a
weight, a percentage from 0 to 100, such as a deal stage's probability;
other values answer 400 objects.options_invalid.
An object's path_field (ADR 0037 §2) is the API name of one of its
active single-value picklists, or null. The record page shows its options
as a path, and the board view groups records by it. PATCH /objects/...
sets it; a field that is not one of the object's single-value picklists
answers 400 objects.path_field_invalid, and null clears it. A field is
not deleted while it is the path (409 objects.field_in_use). A member who
cannot read the field (field permissions) is described an object with no
path_field. Describing an object always returns path_field; device
replicas carry it with the rest of the definition.
Plugin objects¶
Plugins declare objects and fields in their manifest ([[objects]], see
Declaring objects); enabling the plugin in a
workspace creates or migrates them, and only installation creates names in
a plugin's namespace: POST /objects and POST .../fields always create
custom names. Describing a plugin object returns "origin": "plugin" and
"owner_plugin": "<plugin id>", and each of its fields its own origin:
plugin for the plugin's, workspace for the custom fields
administrators add.
PATCH .../fields/{field}andDELETE .../fields/{field}on a plugin's field, andDELETE /objects/{api_name}on a plugin object, answer409 objects.plugin_owned, with one exception: aPATCHof a plugin's related-to field that sends onlyexpected_versionandreference_objectschanges its allowlist (see Related-to fields).PATCH /objects/{api_name}on a plugin object may change onlysharing_modelandgrant_hierarchy; any other setting,path_fieldincluded, answers409 objects.plugin_owned.- Custom fields, validation rules, automations, quick actions and object permissions on plugin objects work as on any object. Role permissions start empty, as for a new workspace object.
While the plugin is disabled or removed in the workspace, its objects are
suspended: every route answers 404 for them as for a missing object,
GET /objects, search, queries, related lists, navigation and device sync
leave them out, and nothing about them changes. Lookup and related-to
values on other objects that point at their records are kept and saved
again unchanged, but are not named in related, and new values to them
are refused like values to a missing record. Enabling the plugin again
brings them back as they were.
Related-to fields¶
A related_to field (ADR 0033 §1) points to a record of any object in an
allowlist set on the field, such as an activity about an account, a deal or
a case. It takes reference_objects, 1 to 10 distinct API names of active
objects, kept in the order given; reference_object stays null. Its
delete behaviour is always clear; it has no default, is never unique and
takes no lookup filter yet.
{"name": "regarding", "label": "Regarding", "field_type": "related_to",
"reference_objects": ["custom:account", "custom:deal"]}
Describing the object returns the field with
"reference_objects": ["custom:account", "custom:deal"],
"reference_object": null and "delete_behaviour": "clear"; other field
types return "reference_objects": null. Creating one fails with:
- objects.reference_objects_invalid when the list is missing, empty, longer
than 10 or names an object twice, or when another type sends one;
- objects.reference_object_unknown when it names an unknown or deleted
object;
- objects.reference_object_invalid when it also sends reference_object;
- objects.delete_behaviour_not_allowed for restrict;
- objects.lookup_filter_not_supported for a lookup_filter, also on
PATCH;
- objects.unique_not_allowed and objects.default_not_allowed.
A plugin's related-to field ("origin": "plugin") may have an empty
allowlist: plugins may ship one empty or partial, and its list takes 0 to
10 objects instead of 1 to 10. While it is empty, every value is refused
with records.reference_object_not_allowed, and so is every object on
the candidates route. Upgrading the plugin never changes it.
PATCH .../fields/{field} takes a new reference_objects, which replaces
the allowlist and is checked the same way; on a plugin's field it may be
the request's only change. An object entering the allowlist of a plugin's
field gains the create quick actions the plugin declares for it
(related actions); one that cannot
be added, because the object already has an action of that name or 10
actions, is skipped and audited as objects.quick_action.skipped, and the
PATCH still succeeds. Taking an object out clears
nothing: values that point to its records stay and are still named in
related, but new values to it are refused, its records lose the field's
related list, and create quick actions on it that fill the field are
deleted. Deleting an allowed object takes it out of every allowlist, as a
field change with its own event, and clears the values that point to its
records outside the recycle bin, each as a record update. An object that
is the only one a related-to field of another object allows cannot be
deleted (409 objects.object_referenced), as for a lookup's target.
Formulas, validation rules and automation formulas cannot use a related-to
field (objects.formula_invalid, rules.condition_invalid), and it cannot
be a roll-up's relationship (objects.rollup_relationship_invalid).
Records¶
| Method and path | Purpose |
|---|---|
GET /objects/{api_name}/records |
List records |
POST /objects/{api_name}/records |
Create a record from name and field values |
GET /objects/{api_name}/records/{id} |
Read a record; include_deleted=true reads it from the recycle bin |
PATCH /objects/{api_name}/records/{id} |
Change only the values sent; null clears; send expected_version |
DELETE /objects/{api_name}/records/{id}?expected_version= |
Move a record to the recycle bin |
POST /objects/{api_name}/records/{id}/undelete?expected_version= |
Restore a record from the recycle bin |
POST /objects/{api_name}/records/{id}/archive?expected_version= |
Archive a record |
POST /objects/{api_name}/records/{id}/unarchive?expected_version= |
Bring an archived record back |
A record carries the standard fields of ADR 0014 (id, object, name,
owner, created_at, created_by, updated_at, updated_by,
touched_at, version, archived_at, is_deleted, deleted_at) followed by
its values keyed by field API name, then related, which maps the id of
each lookup, master-detail or related-to target the caller can read to that
record's name, and related_objects, which maps the same ids to the
target's object API name, so a client can link to a related-to target.
Targets the caller cannot read are left out of both, so a lookup shows only
its id.
{"id": "0a2000000000001AB", "object": "custom:task", "name": "Call Acme",
"custom:regarding": "0a0000000000003CD",
"related": {"0a0000000000003CD": "Acme"},
"related_objects": {"0a0000000000003CD": "custom:account"}}
owner, created_by and updated_by are references to the member's user
record with their display name.
A create may send id to keep an id a device assigned offline (ADR 0031):
it must carry the object's key prefix and come from the device range, or
the create is 400 records.id_invalid. Creating again with the same id
returns the record the caller already created; anyone else's id is
409 records.id_taken. Composite creates and bulk inserts take id the
same way, so offline records that refer to each other push with their
references intact.
Lists accept status: active (the default: live records that are not
archived), archived (live, archived records), all (every live record),
deleted (the recycle bin, archived or not), or any for sync clients, where
deleted records are tombstones and archived ones carry archived_at; sort (name, created_at, updated_at,
touched_at), touched_after (an RFC 3339 time; only records touched
strictly after it), direction (asc, desc), limit (1 to 200), cursor,
search (text the record name contains, at most 100 characters), owner=me and up to ten
filter[{field_api_name}]={value} equality filters on indexed fields. Pages
use keyset cursors that are only valid for the sort and direction that issued
them.
Records of an object with a master-detail field follow their master, through
the first master-detail field created: members see a detail when they can
see its master, and create, edit and delete details when they can edit the
master. The object's own default access, and manual shares, do not apply to
details, and the object is only accessible to roles that can read every
master object. A new detail needs a master the member can edit
(records.master_read_only), and a detail cannot move to another master
(records.master_locked). Deleting a master moves its details to the
recycle bin with it, and restoring the master restores them; a detail whose
master is in the recycle bin cannot be restored on its own
(409 records.master_deleted). A record created while a master-detail field is
being added to its object fails with 409 records.definition_changed;
retrying it applies the new field.
Roll-up values are stored on the master and are read-only
(records.field_read_only). Saving, deleting or restoring a detail updates
its masters' roll-ups in the same request, as a new version of each master
whose summary changed.
Lookup values are record ids. Setting a lookup needs read access to the target
object; an unreadable target is reported like a missing one
(records.reference_not_found). Deleting a target clears referencing lookups
or, for restrict lookups, fails with 409 records.delete_restricted;
undeleting it puts the cleared values back where they were not changed since
(see Recycle bin). A
record in the recycle bin releases its unique values; undeleting it fails with
409 records.duplicate_value if another record took one meanwhile.
Related-to values are record ids too, checked like lookups: the target must
exist and be visible to the writer (records.reference_not_found), and be a
record of an object the field allows now
(records.reference_object_not_allowed, only for a target the writer can
see). A value a change leaves as it was is kept, even if its object was
taken out of the allowlist. Deleting the target always clears the value.
The query language filters a related-to field by =, !=, IN and
NOT IN on record ids, and = null or != null; following it, as in
custom:regarding.name, fails with query.relationship_unsupported.
Related lists and lookup filters¶
Related lists and lookup filters are described in ADR 0028.
| Method and path | Purpose |
|---|---|
GET /objects/{api_name}/records/{id}/related |
The first 5 records of each related list |
GET /objects/{api_name}/records/{id}/related/{object}/{field}?cursor= |
The next 50 records of one related list |
GET /objects/{api_name}/fields/{field}/candidates |
The records a lookup may take, with optional search and cursor; a related-to field needs object, one its allowlist names |
GET /objects/{api_name}/records/{id}/timeline?cursor= |
The record's Activity timeline (ADR 0033 §4): open records and a page of past ones |
A record has one related list for each lookup or master-detail field that
points at its object, and each related-to field whose allowlist names it,
from an object the caller can read, up to 20 lists. Each list has object,
object_label, object_plural_label, field, field_label,
master_detail, field_type (lookup, master_detail or related_to),
data (id and name of records, by name)
and next_cursor. The lists are read as the caller, like a query, so each
member sees only the related records they may see. An unknown relationship
is 404.
A lookup or master-detail field may have a lookup_filter. This is one
condition on the target object, as written after WHERE in a query, such
as custom:active = true, at most 1,000 characters. Setting it checks that
it runs on the target for the caller, with room under the query's
condition limit for the two conditions the engine adds (the record and the
picker's search). Its problems are reported under lookup_filter. Ordering, grouping or limits, or a filter on another field
type, fail with objects.lookup_filter_invalid. Send "lookup_filter": null
on PATCH .../fields/{field} to remove it.
When a member sets a filtered lookup to a new value, the target must meet
the filter (records.lookup_filter_mismatch). Values a change leaves as they
were are kept. Automation writes are not bound by the filter. A filter that
no longer runs, for example after a field it names was deleted, refuses new
values with records.lookup_filter_invalid until it is fixed. Candidates are
the target records the caller sees that meet the filter, by name, 50 to a
page. search matches text the name contains, at most 80 characters. A
related-to field's candidates are those of the object named by object;
leaving it out, or naming an object the field does not allow, fails with
records.reference_object_not_allowed on object.
Activity timeline¶
GET /objects/{api_name}/records/{id}/timeline lists the records of plugin
objects that declare a timeline ([objects.timeline], see
Declaring objects) and point at the record through
one of their declared fields, merged across sources. It runs as the caller,
like related lists: a record the caller cannot read is 404, and only
records the caller may see are listed. Sources whose plugin is disabled, or
whose object the caller cannot read, contribute nothing.
{"sources": 2,
"open": [{"object": "platform.activities:task", "object_label": "Task",
"id": "tsk00000000001AB", "name": "Send the proposal",
"date": "2026-11-12", "date_field": "platform.activities:due_date",
"date_type": "date", "created_at": "2026-11-10T09:12:00.000000Z",
"open": true, "through": "platform.activities:related_to",
"details": [{"field": "platform.activities:status", "label": "Status", "value": "Open"},
{"field": "platform.activities:priority", "label": "Priority", "value": "Normal"},
{"field": "platform.activities:type", "label": "Type", "value": "To do"}]}],
"open_more": false,
"past": [{"object": "platform.activities:event", "object_label": "Event",
"id": "evt00000000002CD", "name": "Kick-off",
"date": "2026-11-09T10:00:00.000000Z", "date_field": "platform.activities:starts_at",
"date_type": "date_time", "created_at": "2026-11-01T08:00:00.000000Z",
"open": false, "through": "platform.activities:related_to", "details": []}],
"next_cursor": null,
"actions": ["log_a_call"]}
sourcescounts the sources that can point at the record and that the caller can read. With none the response is empty, not an error, and the web record page shows no Activity section.openholds open records (a declared picklist value, or a date today or later for"upcoming"), soonest date first, then those without a date, oldest first: at most 50, withopen_morewhen there are more. It comes only with the first page.pastholds every other record, newest first by its date, or bycreated_atwhen it has none; a date counts from midnight UTC. Pages hold 20; passnext_cursorback ascursor. A cursor another timeline issued, or an altered one, is400 timeline.cursor_invalidoncursor.- Each item carries its object's API name and label, the record's
idandname, itsdatewithdate_fieldanddate_type(dateordate_time),created_at,open, thethroughfield that points at the record, anddetails: up to three of the object's picklist values, as their labels, in field order. Everything else is read from the record. actionsnames the record's create quick actions whose target object is a timeline source the caller can read, in quick-action order: the web page offers these in the Activity section. Whether the member may run one is still decided by the target object'screateaccess.
Archiving¶
Archiving (ADR 0035 G1) takes a live record out of everyday use without
deleting it, as Salesforce's archived records are kept: it stays readable by
id, keeps its values, lookups, owner and shares, and can still be changed,
deleted and restored. Archive and unarchive are edits: they need the
object's edit permission and edit access to the record through ownership,
the role hierarchy, a manual edit share or modify_all (ADR 0016), exactly
as an update does, and they take expected_version. Each one moves the
record's version, updated_at, updated_by and touched_at, sets or
clears archived_at, and answers with the record. Neither runs validation
rules or automations, since no value changes.
Archiving is not idempotent. The refusals are, in this order after access:
| Status and code | When |
|---|---|
404 resource.unavailable |
The record does not exist or the caller cannot see it |
403 auth.permission_denied |
The caller can see it but has no edit access |
409 records.deleted |
The record is in the recycle bin; restore it first |
409 records.already_archived |
Archiving a record that is archived |
409 records.not_archived |
Unarchiving a record that is not archived |
409 records.version_conflict |
expected_version is not the current version |
The record's state is checked before its version, so a client that missed someone else's archive learns that rather than seeing a version conflict.
Where an archived record shows:
| Surface | Archived records |
|---|---|
GET .../records/{id} and record history |
shown, with archived_at |
GET .../records |
left out unless status=archived or status=all |
| Record queries and saved reports | left out unless the query sends include_archived=true (or include_deleted=true) |
| Global search | left out |
Lookup and related-to pickers (.../candidates) |
left out |
| Related lists and the Activity timeline | left out |
| Existing lookups to an archived record | kept, with its name in related; paths through the lookup still read it |
| Setting a lookup to an archived record by id | allowed, subject to the field's lookup filter |
Sync (status=any, revocations) |
kept, with archived_at, so devices hold it |
A record in the recycle bin keeps its archived_at: status=deleted lists
it, and undeleting it brings it back archived. On a synced device
archiving and unarchiving are made on the server: the command bridge
answers 403 sync.server_only, and the replica takes the server's
archived_at with each record it pulls.
Recycle bin¶
A deleted record stays in the recycle bin for 15 days (ADR 0014 §5, ADR 0035 G2), archived or not, and can be undeleted until then. The window is an engine constant with no workspace setting. After it, the worker's purge removes the record for good, workspace by workspace, as the platform rather than as a member: the record, its index and search terms, its shares, its history, its change-log entries and the cleared lookups kept for it (below). It runs hourly, in bounded batches of 100 records per transaction and about 30 seconds per workspace per pass, so a large bin empties over several passes; a pass with nothing due changes nothing. A record undeleted before the purge reaches it is never purged: each record is claimed with a write that checks it is still in the bin.
What the purge leaves and adds:
- Audit entries and published events of the record's life stay, as all
evidence does. Each purge transaction writes one audit entry for the
workspace,
records.recycle_bin.purged, with no actor, thesystemsource, the records it removed by object, the cut-off andretention_days, and oneplatform.objects.record-purged.v1event per record (see Events). - A record elsewhere still pointing at a purged record (one undeleted while
its target stayed in the bin) loses the value, as an update with the
systemsource, noupdated_by, a history entry and anupdatedchange. Details of a purged master are purged with it, since they could never be restored. GET /objects/changespages carrypurges, the number of purge transactions that removed records in the workspace. A purged record leaves no change behind, so a synced device that seespurgesmove asks for its revocation set, which now includes the records in its recycle bin (see Device sync).
Deleting a record clears the lookups and related-to values that point to it,
each as an update of the referencing record, as before. Undeleting it puts
each cleared value back (ADR 0035 G3, as Salesforce does) where the
referencing record is out of the recycle bin and has not written that field
since: setting the field to anything, clearing it again included, counts as
a change. Each restore is an update of its own with the next version, a
history entry with the system source, an updated change naming the
field and a record-updated event; validation rules, lookup filters, field
permissions and automations do not apply, as they do not to the clear. A
cleared value is skipped when the referencing record changed the field
(changed), is in the recycle bin (deleted), or the field or its object
is no longer in service (field_removed); skipped values are named, with
their reason, in a records.lookups.restore_skipped audit entry. Details
undeleted with their master get their cleared values back the same way:
the master and every detail coming back with it are restored first, and the
cleared values after, so links between them (a detail to another detail or
to its master, the master to a detail) survive.
What was kept for a record is forgotten once it is undeleted, whether each
value came back or not, or when it is purged.
POST .../records/{id}/undelete answers with the record and
lookups_restored: {"restored": 2, "skipped": 1, "skipped_by_reason":
{"changed": 1}}. These are counts only, since the member may not be able
to read the records involved. A synced device's own undelete answers
without it; the server restores the values when the undelete is pushed and
the device takes them with the next pull.
Change data capture¶
GET /objects/changes returns the workspace's change log after after
(ADR 0018): data holds position, object, record, kind (created,
updated, deleted, undeleted), the changed fields by name (an
archive or unarchive is an updated entry naming archived_at, as an
owner change names owner),
changed_at, changed_by and correlation_id; next_after is where to
resume and head the newest position. Positions are gap-free and in commit
order. Only changes to records the caller can currently see are returned,
but next_after still moves past the others. object limits the page to
one object, and limit takes 1 to 200. Entries never carry values; read
them through the record API.
GET /objects/changes/stream sends the same entries as server-sent events
(event: change, id: the position), resuming after after or the
Last-Event-ID header. Streams end after 15 minutes; reconnect with
Last-Event-ID. Changes are kept for 72 hours: a position older than that
returns 410 changes.position_expired (or an expired event on a stream),
and the client resynchronises with status=any&sort=touched_at&touched_after=
lists.
Each page also carries metadata_version, the workspace's definitions
version (ADR 0024). It increases with every change to an object, field,
object permission, validation rule, automation or quick action, and never with record
changes, which leave no entry for definitions. It is read after the page's
entries, so it is never older than the definitions they were made under. A
stream sends event: metadata with {"metadata_version": n} before the
first entries and again whenever the version moves. These events have no
id:, so Last-Event-ID stays a log position. A synced client fetches
definitions again when the version moves, before it applies the entries
that follow.
Device sync¶
The change log omits records a member can no longer read, so it cannot
tell a device to drop them. POST /sync/revocations takes the records a
device holds, {"records": {"custom:deal": ["a0B…", …]}}, and returns
those the caller can no longer read: {"revoked": {"custom:deal": […]}}.
A record is revoked when its object is gone or no longer readable, or when
the record is missing (never made, or purged from the recycle bin) or no
longer shared with the caller (ADR 0024 §4). A record in the server's
recycle bin is not revoked: the device takes its deletion from the change
log, and keeps it in its own bin until the purge removes it. A device names
the records in its recycle bin too, and asks again whenever a change page's
purges moves (ADR 0035 G2). Records are read as the caller through the query language, so
sharing and object permissions apply as they do to a query. Objects with
nothing revoked are left out. A request names at most 1,000 record ids
(400 sync.manifest_too_large), so a device with more sends its replica in
several requests.
A synced device takes its definitions from the routes above: GET
/objects/assistant-policy, GET /objects, then GET /objects/{api_name},
its validation rules and its quick actions for each object, whenever a change page's metadata_version is newer than the one it
applied. It reads each changed record with include_deleted=true, and pushes
its queued changes as composite requests (ADR 0024). A related-to field
keeps, on the device, only the objects of its allowlist the device holds.
A field the device does not have yet is left out when it holds none of
them; one it already has keeps an empty allowlist instead, so nothing can
be chosen for it offline until an allowed object returns. Values to other
objects are kept as the server sent them and new ones are refused
offline, so the server decides them on push. Device clients ignore related_objects as
they do related.
Query¶
GET /query?q=… runs the record query language (ADR 0019) as the caller:
SELECT name, custom:stage, custom:amount, custom:account.name
FROM custom:deal
WHERE custom:stage IN ('won', 'negotiation') AND custom:close_date = THIS_MONTH
ORDER BY custom:amount DESC
LIMIT 500
- Names are API names; standard fields are
id,name,owner,created_at,created_by,updated_at,updated_by,touched_at,version,is_deleted,deleted_atandarchived_at. A dot follows a lookup, up to three hops. - Conditions:
=,!=,<,<=,>,>=,IN,NOT IN,LIKE,NOT LIKE,= null,!= null, andINCLUDES/EXCLUDESfor multi-select picklists, withAND,OR,NOTand parentheses. Text compares without case. A negated condition includes records without a value. - Literals are typed:
'text', numbers,true,false,null, dates (2026-10-11), date-times (2026-10-11T09:30:00Z) andTODAY,YESTERDAY,TOMORROW,THIS_WEEK,LAST_WEEK,NEXT_WEEK(weeks start on Monday),THIS_MONTH,LAST_MONTH,NEXT_MONTH,THIS_YEAR,LAST_N_DAYS:nandNEXT_N_DAYS:n, in UTC. A date means the whole day or period. WHERE,ORDER BYandGROUP BYtake standard fields, lookups and indexed fields only (query.field_not_indexedotherwise); any field can be selected.- Aggregates:
COUNT(),COUNT(field),SUM,AVG,MIN,MAX, with an optional alias andGROUP BYon up to three fields. Grouped text values come back as their lowercase key. - Sharing applies to the object and to every relationship hop, so a hidden
parent never matches a condition and its selected fields are
null. Archived records are left out, as lists leave them out:include_archived=trueadds them, andinclude_deleted=trueadds records in the recycle bin, archived or not. A cursor works only with the flags it was issued with.
The response holds object, columns (key and type), data (rows keyed
by each selected item or alias; record rows always carry id) and
next_cursor. Record queries page with cursor and page_size (1 to 200,
default 200); a cursor only works with the same query. Problems are
400 validation.failed with field: "q", a stable code
(query.syntax, query.object_unknown, query.field_unknown,
query.field_not_indexed, query.formula_not_filterable,
query.relationship_unknown,
query.operator_invalid, query.value_invalid, query.too_complex,
query.too_many_groups, query.cursor_invalid) and a detail naming the
position; a query that runs past its time limit returns
503 query.timeout. Limits are listed in ADR 0019.
Validation rules¶
Per-object rules (ADR 0021) live at /objects/{object}/validation-rules.
GET lists them: every rule for administrators with objects.manage, and
the active rules for anyone else who can read the object, so a synced device
checks them offline. Administrators create one with POST, and change or
remove one with PATCH / DELETE …/validation-rules/{name} and
expected_version.
{"name": "won_needs_close", "condition": "ISPICKVAL(custom:stage, 'won') && ISBLANK(custom:close_date)",
"message": "Won deals need a close date", "error_field": "custom:close_date", "active": true}
conditionis a formula that is true when the record is wrong. It is type-checked when saved; problems are400withrules.condition_invalidand the position. Other codes:rules.name_invalid,rules.message_invalid,rules.field_unknown,rules.limit_reached(100 per object) and409 rules.duplicate_name.- The language has numbers, text, booleans, dates and date-times; fields by
API name, following lookups with a dot (up to three); operators
+ - * / & = != < <= > >= && || !; andIF,CASE,AND,OR,NOT,ISBLANK,BLANKVALUE,ISPICKVAL,INCLUDES,LEN,LOWER,UPPER,TRIM,LEFT,RIGHT,MID,CONTAINS,BEGINS,SUBSTITUTE,TEXT,VALUE,ABS,FLOOR,CEILING,ROUND,MOD,MIN,MAX,TODAY,NOW,DATE,DATEVALUE,YEAR,MONTH,DAY,ADDMONTHS,REGEX,ISNUMBER,FIND,LPAD,RPAD,SQRT,EXP,LN,LOG,TRUNC,WEEKDAY,DATETIMEVALUE,PICKLISTWEIGHT,PICKLISTOUTCOME,ISNEW,ISCHANGEDandPRIORVALUE. Formula fields can be used like other fields; their formulas are inlined, with cycles refused. PICKLISTWEIGHT(field)andPICKLISTOUTCOME(field)read a single-value picklist's current option (ADR 0037 §1), on the record or through lookups: its weight, a number (blank when the option has none), or its outcome,open,positiveornegative. Both are blank when the field is blank or holds a value that is no longer an option. They follow the options as they are when the formula runs, so changing a weight changes the results.- Active rules run on every create, update and owner change. A save that
breaks rules fails with
400 validation.failed; each broken rule is an error withcode: records.validation_rule, its message, and itserror_fieldorrecord. A rule that cannot be evaluated (division by zero, an invalid date) reportsrecords.validation_rule_errorand also blocks the save. - Rules read lookup targets whatever the saving member can see.
- Deleting a field an active rule needs fails with
409 objects.field_in_use.
Quick actions¶
Per-object shortcuts (ADR 0032) live at /objects/{object}/quick-actions.
GET lists them by position, then name, to anyone who can read the
object; to anyone else the object is unknown. Administrators with
objects.manage create one with POST, and change or remove one with
PATCH / DELETE …/quick-actions/{name} and expected_version (in the
body for PATCH, as a query parameter for DELETE). An action grants
nothing: running it uses the normal record create and update APIs.
{"name": "add_contact", "label": "Add contact", "kind": "create", "position": 1,
"target_object": "custom:contact", "target_field": "custom:account",
"fields": ["name", "custom:email"], "presets": {"custom:role": "buyer"}}
kindisupdate(a short form of this object's fields) orcreate(a form for a child record). A create action names itstarget_objectandtarget_field, an active lookup or master-detail field on that object pointing to this one, or a related-to field whose allowlist names this object, which is set to the current record; an update action has neither.kind,target_objectandtarget_fieldcannot change;PATCHtakeslabel,position,fieldsandpresets.nameis[a-z][a-z0-9_]{0,62}and unique per object;labelis 1 to 80 characters;positionis 0 or more and defaults to after the existing actions.fieldslists 1 to 20 distinct field API names, the record name asname, of this object forupdateand of the target object forcreate.presetsmaps up to 20 such fields to constant values, checked and normalised as record values are; a preset need not be infields. Formula and roll-up summary fields, and a create action'starget_field, cannot be chosen or preset.- Problems are
400withquick_actions.name_invalid,quick_actions.label_invalid,quick_actions.position_invalid,quick_actions.target_required,quick_actions.target_not_allowed,quick_actions.target_object_unknown,quick_actions.target_field_invalid,quick_actions.fields_invalid,quick_actions.presets_invalid,quick_actions.field_duplicate,quick_actions.field_unknown,quick_actions.field_not_allowed(onfields.{field}orpresets.{field}), a record value code such asrecords.value_typeonpresets.{field},quick_actions.limit_reached(10 per object) and409 quick_actions.duplicate_name. - The web record page shows the actions in this order next to Edit and
Delete: an update action only on records the member may edit, a create
action only when the member may create the target object. An update
action's form shows only its
fieldsand saves their changes with all of its presets through the record update API; a create action's form shows itsfieldswith thetarget_fieldset to the current record, read-only, and sends its presets, shown or not, on create. A preset field the form also shows starts at the preset, and the member may change it. Administrators manage the actions in the Object Manager. - Deleting a field removes it from the
fieldsandpresetsof the actions that use it; an action left with no fields is deleted. Deleting a create action'starget_fieldor target object deletes the action, as does taking this object out of a related-totarget_field's allowlist, and deleting an object deletes its own actions. Each change publishes its quick-action event in the same transaction and moves the workspacemetadata_version, including the related actions a plugin adds. - A synced device takes each object's actions from this
GETwith its other definitions (ADR 0032 §5, #236) and keeps only those it can run offline: theirfieldsandpresetsare fields the device holds on this object and, for a create action, itstarget_objectis held and in service and itstarget_fieldstill points here. Any other action, such as one that names a lookup to an object the member cannot read, or makes records of a plugin object suspended with its plugin, stays with the server and comes back with what it needs; the sync report lists it as deferred. A device answers thisGETfrom its replica, with the same shape, and refuses action changes with403 sync.server_only. Running an action on the device is the ordinary local create or update as the member, which the server checks again when it is pushed.
Assistant policy¶
What a device's assistant bridge (ADR 0034, #234) may reach is object metadata. Every setting is off until an administrator turns it on, and the policy only narrows: assistants act as the member, after the member's permissions and sharing, and the policy grants nothing.
GET /objects/assistant-policyreturns the workspace switch with the policy of every object the caller can read (every object for holders ofobjects.manage):
{"enabled": true, "version": 2, "updated_at": "…", "updated_by": {"id": "…", "name": "…"},
"objects": [{"object": "custom:deal", "exposed": true, "writable": true, "indexable": true,
"excluded_fields": ["custom:amount"], "offered_actions": ["close"],
"version": 3, "updated_at": "…", "updated_by": {"id": "…", "name": "…"}}]}
A workspace or object that never had a policy reads as everything off
with version: 0 and updated_at: null.
- PATCH /objects/assistant-policy with {"expected_version": 2,
"enabled": false} turns assistant access on or off for the workspace.
- GET /objects/{object}/assistant-policy returns one object's policy to
anyone who can read the object; to anyone else the object is unknown.
PATCH with expected_version changes any of exposed, writable,
indexable, excluded_fields and offered_actions; what it leaves out
stays as it is.
- exposed: assistants may find and read the object's records, as the
member. writable: they may create and update them, each change confirmed
by the member; it requires exposed. indexable: devices may put the
records into the phone's search index; it requires exposed.
excluded_fields lists the fields, the record name as name, whose values
never enter that index; they apply to the index only, never to assistant
reads, which field-level security decides. offered_actions lists the
quick actions offered to assistants, at most 10: each requires exposed,
and the object it writes (this object for an update action, the target
object for a create action) must be writable.
- Changes need objects.manage, otherwise 403 auth.permission_denied. A
plugin's installation never sets the policy, so a plugin object follows the
workspace's like its sharing model and starts off; a suspended plugin
object is unknown here too. Problems are 400 with
assistant_policy.requires_exposed (on writable, indexable or
offered_actions.{name}), assistant_policy.field_unknown and
assistant_policy.field_duplicate (on excluded_fields.{field}),
assistant_policy.action_unknown, assistant_policy.action_duplicate and
assistant_policy.action_not_writable (on offered_actions.{name}), and
assistant_policy.actions_invalid; a stale expected_version is 409
records.version_conflict.
- Fields and actions are kept by id: a deleted field or action leaves the
policy, and one made again under the same name is not excluded or offered.
Turning writable off takes the create actions of other objects that make
its records out of their objects' offered_actions, each as its own change.
- Each change is audited (objects.assistant_settings.updated,
objects.assistant_policy.updated) and publishes
platform.objects.assistant-policy-updated.v1 with scope (workspace or
object) and the settings by API names in the same transaction, and moves
the workspace metadata_version.
- A synced device reads GET /objects/assistant-policy with its other
definitions and keeps each object's policy against its own fields and
quick actions; names it does not hold are left out, and a server that does
not answer leaves assistant access off on the device. A device answers both
GET routes from its replica and refuses PATCH with 403
sync.server_only.
Assistant writes on push¶
A create or update in a composite request may carry an assistant marker (ADR 0034 §6, ADR 0017 "Change source" rule 3 as amended), which only a synced device's push sends for a change its assistant bridge made:
{"method": "update", "reference": "r0", "object": "custom:deal", "id": "a0B…",
"expected_version": 4, "values": {"custom:stage": "won"},
"assistant": {"assistant": "siri", "quick_action": {"object": "custom:deal", "name": "close"}}}
assistantissiriorgemini; any other name makes the request invalid.quick_action, when the assistant ran one, names the action by its object and API name.- The marker only adds checks. The operation first passes every check it
would pass unmarked; then, in the same transaction, the server checks its
current policy: assistant access on, the written object exposed and
writable, and a named quick action offered on an exposed object and
writing this object this way (an update action updates its own object, a
create action creates its target object). Otherwise the operation fails
with
403 assistant.not_allowed, and the device keeps the change like any write the server refuses. - Only a request a device's token authenticated may carry it; anything else,
a device's own command bridge included, fails the operation with
400 assistant.marker_not_accepted. - The change's source is
{"kind": "assistant", "detail": "siri"}in history and audit, and the audit entry keeps the verified device id asdevice_idbeside it. Events carry only the kind.
Record drafts¶
Record forms keep the member's unfinished input as a draft (ADR 0036). A draft lives on the member's device, never on the server: in the browser, IndexedDB encrypted with a per-browser key the server holds. A draft is not a record change: writing one creates no record version, history entry, event, change-log entry, audit entry or sync push, and saving one is the ordinary create or update with every check. The server keeps only the workspace's expiry and each browser's key.
Draft settings¶
GET /objects/draft-settings returns the workspace's draft expiry to any
member; PUT /objects/draft-settings with {"expiry_days": 14,
"expected_version": 0} changes it and needs objects.manage.
{
"expiry_days": 14,
"default_expiry_days": 7,
"min_expiry_days": 1,
"max_expiry_days": 90,
"version": 1,
"updated_at": "2026-11-18T09:30:00Z",
"updated_by": {"id": "…", "name": "Hannah Okafor"}
}
- A draft expires
expiry_daysafter its last change. Without a change the workspace has the default of 7 days, atversion0 withupdated_atandupdated_bynull. Browsers compute expiry from the current setting, so shortening it removes older drafts at their next sweep. expected_versionis the version read (0 for the default); a stale one returns409 records.version_conflict. Values outside 1 to 90 return400 validation.failedwithdrafts.expiry_invalidonexpiry_days; unknown fields are refused.- A change writes an audit record (
objects.draft_settings.updated, targetdraft_settings, with the old and new number of days) andplatform.objects.draft-settings-updated.v1in the same transaction, and moves the workspacemetadata_version. It writes no change-log entry. - The setting is engine metadata in both stores (
record_draft_settings, keyed bytenant_id, forced row-level security on PostgreSQL). A synced device answers theGETfrom its replica and refuses thePUTwith403 sync.server_only. - The web shell offers the setting as Settings → Record drafts to holders of
objects.manage.
Where drafts live¶
The workspace's UI contributions (GET /ui/contributions) carry a drafts
block naming where the shell keeps drafts, with the expiry and the limits:
The server always says browser. A host that sends no block (or null)
keeps no drafts, and forms behave as before; the device bridge sends none
until device drafts exist (ADR 0036 slice 3). The block is part of the
contribution revision, so a changed expiry reaches open shells on their
next revalidation. Limits: 50 drafts per member per workspace in one browser
(new forms then stop autosaving; nothing is evicted), and 1 MiB per draft
document before encryption.
The browser draft key¶
GET /api/v1/me/draft-key?browser={browser id} returns the signed-in
user's key for that browser, creating it on first use:
- Browser sessions only: a request with an
Authorizationheader (an API client's or a device's token) is refused with403 drafts.browser_onlybefore the session is looked at; no session is401 auth.unauthenticated.browsermust be a UUID (400 drafts.browser_invalid). - The response is
Cache-Control: no-store. Keys are random, never logged and never audited, and never returned to another user. - Keys are user-scoped (
draft_keys, next to sessions): one per user and browser, at most 20 per user (creating a 21st deletes the least recently used), deleted by the worker after 90 days unused, and deleted with the user. - The shell derives a per-workspace AES-256-GCM key with HKDF-SHA-256
(salt: the workspace id; info:
limiara.record-drafts.v1), keeps it in memory only as a non-extractable key, and encrypts each draft with a fresh 96-bit nonce and associated data naming the format version, member, workspace and draft id. Without a key the form says "Drafts are unavailable" and writes nothing.
Sign-out¶
POST /auth/logout?browser={browser id} revokes the session and, in the
same transaction, deletes that browser's draft key, so drafts left in the
browser can no longer be decrypted. The web shell's Sign out deletes the
member's drafts in the browser first, then posts. Without browser (or with
one that is not a UUID) sign-out revokes the session only.
Formula fields¶
A field with "field_type": "formula" takes a formula and a
formula_type (text, number, currency, percent, boolean, date
or date_time; scale sets decimal places for numbers):
{"name": "total", "label": "Total", "field_type": "formula",
"formula": "custom:amount * (1 + custom:tax_rate / 100)", "formula_type": "currency"}
Its value is computed whenever a record is read and appears with the other
field values; lookups follow the reader's sharing, so a hidden target reads
as blank. Problems with the formula are 400 objects.formula_invalid with
the position; writing a value is records.field_read_only. Formula fields
cannot be required, unique, indexed, searchable, tracked or defaulted.
Queries can select every formula field. A formula that reads only its own
record (no lookups, no TODAY or NOW) has a stored value, and queries
can also filter, sort and aggregate on it. Using any other formula in those
clauses is 400 query.formula_not_filterable. PATCH with formula changes
the formula; a change that would break a formula, rule or automation using
this field is 409 objects.field_in_use.
Composite requests¶
POST /composite runs up to 25 record operations in one call (ADR 0023):
{"all_or_none": true, "operations": [
{"method": "create", "reference": "acme", "object": "custom:company", "values": {"name": "Acme"}},
{"method": "create", "reference": "ada", "object": "custom:person",
"values": {"name": "Ada", "custom:employer": "@{acme.id}"}},
{"method": "update", "reference": "renamed", "object": "custom:person", "id": "@{ada.id}",
"expected_version": 1, "values": {"name": "Ada L."}}]}
methodiscreate,update,delete,undelete, which restores a record from the recycle bin, orchange_owner, which takesowner_idand transfers the record asPOST .../ownerdoes: an owner who is not a member of the workspace rejects the request with400 records.owner_unknownonoperations[i].owner_id. All butcreatetakeidandexpected_version.referenceis unique and names the operation.- A whole string value of
"@{reference.id}", includingid, means the public ID of an earlier operation's record. Using a failed or later operation iscomposite.reference_unknown. - Without
all_or_none, each operation runs on its own and a failure does not stop the rest. With it, they share one transaction, and the first failure rolls everything back: earlier operations report409 composite.rolled_backand later ones424 composite.not_run. - The response is
200withresults, one per operation in order. Each hasreference,statusandbody: the record, or the problem the single-record route would return. - Problems with the request itself are
composite.operations_invalid(1 to 25 operations) andcomposite.reference_invalid. - A create or update a device pushes for its assistant bridge carries an
assistantmarker, checked against the assistant policy (Assistant writes on push).
API clients¶
Integrations call the routes on this page with an OAuth 2.0 client-credentials token instead of a session (ADR 0023 §3).
- An administrator with
api_clients.managecreates a client:POST /api-clientswith{"name": "Nightly sync"}. The client acts as the administrator. To act as another member, send"run_as"with that member's id; this also needsmembers.manage. The201response includesclient_idandclient_secret. The secret is shown only this once. - The integration exchanges the credentials for a token:
curl -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials \
https://api.example.com/oauth/token
The response is {"access_token", "token_type": "Bearer",
"expires_in": 3600, "workspace_id"}. Failures use OAuth's error codes:
- 401 invalid_client for unknown or revoked clients, wrong secrets,
and clients whose member left;
- 400 unsupported_grant_type or 400 invalid_request for other
problems.
3. It sends Authorization: Bearer <token> to the workspace's object
routes and to query, search, composite, bulk and sync. It has exactly
its member's access. Other routes return
403 auth.client_route_denied, and an unknown or expired token returns
401.
GET /api-clients lists clients without secrets, and
POST /api-clients/{id}/revoke revokes one along with its tokens. A
workspace has at most 20 active clients (409 api_clients.limit_reached).
Devices¶
Phone and desktop apps sign a member in through the system browser and
call the routes on this page with their own tokens (ADR 0029). The
deployment lists each app's redirect URI in
platform.devices.redirect_uris: a private-use scheme such as
com.example.app:/oauth, or HTTP to a loopback address.
- The app creates a PKCE verifier and opens the system browser at
GET /auth/device/login?redirect_uri=…&code_challenge=…&code_challenge_method=S256&state=…. An unregistered redirect URI is400 auth.device_redirect_invalid, and a missing or plain challenge is400 auth.device_challenge_invalid. The person signs in with the identity provider, as on the web, and the browser returns to the redirect URI withcodeandstate. - Within two minutes, the app redeems the code:
curl -d grant_type=authorization_code -d code="$CODE" -d code_verifier="$VERIFIER" \
-d redirect_uri=com.example.app:/oauth -d workspace_id="$WORKSPACE" \
-d device_name="Ana's phone" -d platform=ios \
https://api.example.com/oauth/token
The response is {"access_token", "token_type": "Bearer",
"expires_in": 3600, "refresh_token", "workspace_id", "device_id",
"offline_limit_seconds"}. A code works once, for the verifier that
started the sign-in; anything else is 400 invalid_grant. A member has
at most 10 active devices per workspace.
3. The access token reaches the same routes as an API client's, with the
member's access, plus the device's own routes below.
4. Before it expires, the app sends grant_type=refresh_token with
refresh_token. Each use returns a new refresh token, and the old one
stops working. Presenting a used refresh token again revokes the
device.
When a device is revoked, or its member leaves the workspace, its access
token gets 401 auth.device_wipe_required and its refresh token
400 invalid_grant with "wipe": true. The app then deletes the
workspace's data. After offline_limit_seconds without reaching the
server, the app locks its data until it signs in again.
GET /deviceslists the caller's devices, or everyone's withdevices.manage:name,platform(ios,android,desktop),member,push(the provider, never the token),last_seen_at,revoked_at,revoked_by,revoked_reason(revoked,signed_out,refresh_reused) andcurrent.POST /devices/{id}/revokerevokes one of the caller's devices, or anyone's withdevices.manage. Others' devices are404.- With the device's own token only:
GET /devices/currentreturns the device, itsmember(id,display_name,email,permissions,rolesby name androle_ids) and theworkspace(id,name), which the app builds its replica's engine from;DELETE /devices/currentsigns the device out,PUT /devices/current/pushwith{"provider": "apns" | "fcm", "token": "…"}sets where its push notifications go, andDELETE /devices/current/pushstops them.
A device with a push token gets a background notification when its
workspace's change log or metadata version moves, at most once every
platform.devices.push.quiet_seconds (ADR 0030). It carries only
workspace_id: the app wakes and pulls GET /objects/changes as usual. A token the
provider reports invalid is forgotten, and the app registers again.
Bulk jobs¶
POST /bulk queues up to 5,000 rows to insert, update or delete in the
background (ADR 0023 §2), and returns 202 with the job:
{"object": "custom:person", "operation": "update", "rows": [
{"id": "0a1000000000000001", "values": {"name": "Ada L."}},
{"id": "0a1000000000000002", "expected_version": 3, "values": {"name": "Grace H."}}]}
operationisinsert,updateordelete. Insert rows are the record's values. Update rows takeid,valuesand an optionalexpected_version; delete rows takeidand an optionalexpected_version. Without one, a row uses the record's current version.- The caller needs create, edit or delete access to the object. Malformed
rows reject the job with
bulk.row_invalidagainstrows[i], and an empty or oversized job isbulk.rows_invalid. - The worker applies each row as its own change, with the caller's access as it is when the row runs, and the same validation, automations and evidence as the single-record routes.
GET /bulk/{id}returnsstatus(queued,running,completedoraborted),total,succeededandfailed. Only the submitter and administrators withobjects.managesee a job.GET /bulk/{id}/results?status=&after=&limit=lists rows in order, up to 1,000 at a time, each withindex,status(pending,succeededorfailed),record(the public ID) anderrors(the code the single-record route would return, and validation issues). Passnext_afterasafterfor the next page.POST /bulk/{id}/abortstops a queued or running job; applied rows stay applied. A finished job is409 bulk.job_state.
Automations¶
Administrators with objects.manage manage record-triggered automations
(ADR 0022) at /objects/{object}/automations: GET lists them in the order
they run, POST creates one, and PATCH / DELETE …/automations/{name}
change or remove one with expected_version.
{"name": "follow_up", "trigger": "create", "timing": "after_save",
"condition": "custom:amount >= 1000",
"actions": [{"type": "create_record", "object": "custom:task", "values": [
{"field": "name", "formula": "'Follow up ' & name"},
{"field": "custom:deal", "formula": "id"},
{"field": "custom:due", "formula": "TODAY() + 7"}]}]}
triggeriscreate,update(including owner changes),create_or_update,deleteorundelete.timingisbefore_saveorafter_saveand cannot change.deleteandundeleterun after saving only (automations.trigger_invalid).- A
before_saveautomation has oneupdate_recordaction, which sets fields on the record being saved before validation rules run. Anafter_saveautomation has 1 to 10 actions:update_relatedwith alookupon the record, orcreate_recordwith anobject. - Each value is a formula evaluated on the saved record, in the language of
validation rules, including
ISNEW,ISCHANGEDandPRIORVALUE. It is type-checked against the field it sets.conditionis an optional boolean formula, and empty text clears it. - Problems name their place, such as
actions[0].values[1].formula, with codesautomations.formula_invalid,automations.condition_invalid,automations.field_invalid,automations.lookup_invalid,automations.object_unknown,automations.actions_invalid,automations.value_requiredandautomations.limit_reached, plus409 automations.duplicate_name. - Automations run in system context in the save transaction. When one
fails, the member's save fails with
400 validation.failedand an error withfield: "record"andcode: records.automation_failedthat names the automation and the reason. Automations stop at 5 levels deep and 100 saves per change. - Deleting a field an active automation needs fails with
409 objects.field_in_use. - Records that after-save actions save carry
automation_idin their events and audit entries. timing: "async"runs the actions in the background shortly after the change.timing: "scheduled"runs them at a time set by"schedule": {"offset_minutes": 60, "from": "custom:due"}, wherefromis a date or date-time field or is left out for the time of the change. Both can also useupdate_recordon the record they ran for. A job is queued with the change and run by the worker as the member who made it. Failed attempts are retried with backoff, up to 5. Problems includeautomations.schedule_invalid.- Every action can have a
whenformula: it runs only when that holds, so an automation can branch.{"type": "publish_event", "event": "order_placed", "values": [{"field": "total", "formula": "custom:total"}]}publishes aplatform.objects.workspace-event.v1event through the outbox, carrying the event name, object, record, automation and fields. It is not allowed before saving. Problems includeautomations.event_invalid. GET …/automations/{name}/jobs?limit=lists the automation's jobs, newest first:status(pending,running,succeeded,failedorcancelled),due_at,attemptsandlast_error.POST …/jobs/{id}/retryretries a failed job, andPOST …/jobs/{id}/cancelcancels a pending one. Any other state is409 automations.job_state.GET …/automations/{name}/runs?limit=&cursor=lists the automation's runs from the last 30 days, newest first, withnext_cursor. Each run has the record,event,outcome(succeededorfailed, withdetail),saves,ran_atandran_by. A failed run's change was rolled back.
Search¶
GET /search?q=… searches every searchable object the caller can read
(ADR 0020). Each query term matches the start of a word in a record's name
or in a field marked searchable; every term must match. Results are grouped
by object, best group first:
{"data": [{"object": "custom:account", "label": "Account", "plural_label": "Accounts",
"records": [{"id": "0a1000000000000001", "name": "Acme Industries", "fields": {"custom:email": "[email protected]"}}],
"has_more": false}]}
- Names count more than fields, exact words more than prefixes; ties sort by name.
- Sharing applies per object, and records in the recycle bin are never
returned.
fieldsholds up to three searchable field values. limitsets the records per object (default 5, at most 50).objectsearches one object only, with up to 200 records, for a results page.- Queries need at least two letters or digits (
400 search.too_short) and at most 200 characters (search.too_long); other codes aresearch.limit_invalidandsearch.object_unknown. - The index is updated in the same transaction as each record change, so a saved record is found at once.
History¶
Objects with track_history keep each record's lifecycle, name and owner
changes; fields with track_history also keep their old and new values
(ADR 0017). GET /objects/{api_name}/records/{id}/history returns entries
newest first with kind (created, changed, deleted, undeleted,
archived, unarchived),
field, old_value, new_value, changed_at and changed_by; owner
changes also carry old_user and new_user. related names lookup values
the caller can see, and cursor and limit (1 to 200) page through older
entries. History follows record visibility, includes records in the recycle
bin and hides retired fields. Set the flags with PATCH /objects/{api_name}
and PATCH /objects/{api_name}/fields/{field}.
Each entry also has source: what the change came through (#233, ADR 0017
"Change source"), as {"kind": "...", "detail": "..."}, or null for
entries written before sources were recorded. kind is one of web (a
browser session), api_client (an API client's token; detail is the
client's id), device (a synced device's token or its replica; detail is
the device id when known), automation (detail is its API name),
quick_action (its API name), assistant (a device assistant such as
siri), import (a bulk job; detail is the job id) or system.
detail is omitted when there is none. The server sets the source from
what authenticated the request; no header or body field sets it, and it
never changes what the caller may do. Audit entries carry the same
source in their metadata; outbox events carry only source as the kind,
without the detail.
Sharing and ownership¶
Record access follows ADR 0016. Object permissions set the ceiling; within
it a caller sees a record when they hold view all or modify all, own it,
manage its owner through the reporting line (when the object's
grant_hierarchy is on), the object's sharing_model is read or
read_write, or the record is shared with them or one of their roles. A
record the caller cannot see is 404 everywhere: reads, edits, lists,
lookups and related names.
A single-record read carries access: read, edit, delete, share
and transfer for the caller, so clients offer only the actions that will
succeed.
| Method and path | Purpose |
|---|---|
GET /objects/{api_name}/records/{id}/sharing |
Owner, the caller's rights and the manual shares with grantee names; needs the right to share |
PUT /objects/{api_name}/records/{id}/sharing/{user\|role}/{grantee_id} |
Grant or change {"access": "read" \| "edit"} |
DELETE /objects/{api_name}/records/{id}/sharing/{user\|role}/{grantee_id} |
Revoke a share |
POST /objects/{api_name}/records/{id}/owner |
Transfer with {"owner_id", "expected_version"}; removes manual shares |
GET /users |
Workspace members with manager_id, plus can_manage |
PUT /users/{id}/manager |
Set or clear {"manager_id"}; needs members.manage; cycles return 409 members.reporting_cycle |
GET /roles |
Workspace role names, for role shares |
Owners, their managers and modify-all holders share; an edit share never
grants delete or the right to share further. Transferring needs edit access plus ownership,
modify all or records.transfer. Unknown grantees return 400
records.grantee_unknown, unknown new owners 400 records.owner_unknown,
and sharing with the owner 400 records.share_owner. Shares and transfers
emit platform.objects.record-sharing-changed.v1 and
platform.objects.record-owner-changed.v1.
Reports¶
Saved reports (ADR 0027) are record queries with a name and a way to show their rows. A report runs as whoever opens it, so a shared report shows each member only the records they can see.
| Method and path | Purpose |
|---|---|
GET /reports |
The reports the caller sees, and can_manage |
POST /reports |
Save a report |
GET /reports/{id} |
The report and its rows, run as the caller (cursor, page_size) |
PATCH /reports/{id} |
Change only the values sent; send expected_version |
DELETE /reports/{id}?expected_version= |
Delete a report |
A report has a name (1 to 80 characters), an optional description, a
query in the query language, a chart and a visibility:
- chart is table (the default), bar, line, pie or metric;
- charts take a value_column, a number, currency or percent column of the
query; bar, line and pie charts also take a label_column;
- visibility is private (its owner, the default) or workspace (every
member).
Saving checks that the query runs for the caller, and reports its problems
under query with the query language's codes. A chart column that is not
in the query fails with reports.value_column_invalid or
reports.label_column_invalid. Sharing a report with the workspace, and
changing or deleting someone else's report, needs reports.manage; a
private report of someone else is missing. A workspace keeps at most 1,000
reports (409 reports.limit_reached); concurrent saves are serialised, so
they cannot exceed it.
Each report carries can_edit: whether the caller may change or delete
it (its owner, or a member with reports.manage), and owner_plugin: the
plugin that provides it, or null (ADR 0037 §5). A plugin's reports are
shared with the workspace and owned by the member who enabled the plugin.
Changing one keeps it as the workspace made it through the plugin's
upgrades; deleting one means the plugin never adds it again. While the
plugin is not enabled, its reports are missing from the list and from
GET /reports/{id}. The run result is under
result, in the shape of GET /query; pass its next_cursor back as
cursor for the next page of rows.
Navigation¶
Objects marked in_navigation that the caller can read are added to the
workspace's UI contributions (GET /ui/contributions) as
objects.{api_name} entries routed to /o/{api_name}, after feature
navigation. The contribution revision changes when object navigation or
the caller's engine permissions change, so the shell refreshes without a
reload. The engine permissions the caller holds (objects.manage,
records.view_all, records.modify_all, reports.manage) are listed with
the feature permissions. A reports entry routed to /reports
follows the objects.
Errors¶
Errors use the problem format with a stable code. Validation failures
return 400 validation.failed with an errors list of {field, code,
detail}. Version mismatches return 409 records.version_conflict.
Changing a field the caller reads but may not change returns
403 records.field_not_writable, with the fields in errors.
A pushed assistant write the workspace's assistant policy does not allow
returns 403 assistant.not_allowed, and an assistant marker on anything but
a device's push 400 assistant.marker_not_accepted (see
Assistant policy).
Changing or deleting what a plugin owns returns 409 objects.plugin_owned;
the codes for refused plugin installations are listed in
Declaring objects.
Events and audit¶
Every mutation writes an audit record and a platform.objects.*.v1 event in
the same transaction: object, field and object-permission changes, record
created, updated, deleted, undeleted, archived and unarchived
(record-archived, record-unarchived, with the record payload), records
purged from the recycle bin (record-purged, one per record, with one
records.recycle_bin.purged audit entry per purge transaction rather than
one per record), and reports created, updated and
deleted (report-created, report-updated, report-deleted, naming the
report, chart and visibility but not the query), the record draft expiry
(platform.objects.draft-settings-updated.v1, naming the old and new number
of days), and quick actions created,
updated and deleted (platform.objects.quick-action-created.v1,
-updated.v1, -deleted.v1, naming the object, the action, its kind and
target, its fields and the fields it presets, never the preset values), and
assistant policy changes (platform.objects.assistant-policy-updated.v1). Payloads name the object, record and
changed fields, never field values; lookup and related-to values, which
are record ids, are no exception. Changes a plugin's installation makes
also carry "plugin": "<plugin id>", with the member who changed the
plugin's state as actor; suspending and resuming a plugin's objects are
object-updated events with "suspended", audited as
objects.object.suspended and objects.object.resumed. A related action the
engine skips leaves only an audit record, objects.quick_action.skipped,
naming the object, the action, the plugin and the reason; nothing changed,
so no event is published.