/api/v1/db
POST /db/{objecttype} — Create or update objects of any object type.
POST /db/{objecttype} — Create or update objects of any object type.Create or update objects. Replace {objecttype} in the URL with the name
of an object type from this instance's datamodel.
The request body is an array, so multiple objects can be created or
updated in a single call. Each object carries an _objecttype matching
the URL and a _mask. An object is created when it has no _version
(or _version is 1) and updated otherwise; on update the supplied
_version must match the version currently stored.
On create, _id (unique per object type) and _system_object_id (unique
per instance) are assigned from a server-side counter that is not rolled
back with the request: ids are never reused, and a save that fails after
they are drawn leaves a gap in the numbering. Gaps are expected.
Saving an object requires the read permission on a linked object only
when the save introduces that target at a new location — a field, or
a nested row (identified by its _uuid) and sub-field, where the object's
committed version did not already link it. A target sent back at the same
location is exempt, even if its row moved position or other rows around it
were removed. Moving a link to a different field or nested row, or
replacing it with a not-previously-linked target there, requires read on
that target; a caller with write on the object but no read on it is
then rejected with 403 ObjectInsufficientRights (right: read). Being
linked elsewhere in the same object is not enough — it must be the same
location. The frontend round-trips the _uuid of existing nested rows, so
ordinary edits keep their unchanged links exempt.
Differs from easydb 5: both create and update use POST, and create
versus update is decided by _version (create when absent or 1), not by
whether _id is set. easydb 5 distinguishes the two by HTTP method —
PUT to create with no _id, POST to update with _id set.
Access token in the Authorization header:
Authorization: Bearer <token>.
Name of the object type, as defined in the instance's datamodel.
Render format for the objects returned in the response. This only affects the representation sent back to the client, not how the request body is interpreted.
standardPossible values: If set, fylr runs the validation of the save — schema and constraint checks together with the permission checks — but stops before persisting anything and returns the objects it would have written. Use this to check a payload without changing any data.
Because nothing is written, no ids are assigned: an object that
would be created comes back without an _id or _system_object_id
(these are drawn only when the object is actually stored). On an
update the existing ids are echoed back unchanged.
ID of a collection. When set, the objects created by this request are additionally linked into the collection with this ID. Must be a positive integer.
Controls what happens to an object's collection memberships when the update makes it an invalid member of a collection.
setinvalid: keep the link but flag it as invalid.remove: remove the object from the affected collections.
Number of days the signed file URLs contained in the response stay valid. If omitted, the expiry configured for the instance is used.
Controls how the save treats reverse-nested objects, which are governed by their top-level object. This is primarily a save-path switch, not just a response option.
By default (flag not set), the reverse-nested objects currently
attached to the top-level object are reconciled against the payload:
any that the object still has but that are omitted from the
request are deleted (with a <reverse nested delete: …> comment).
To keep one you do not need to resend it in full — include it with
its current _version unchanged and it is left untouched. Reverse-
nested reached through a field that is read-only in the _mask are
never deleted this way.
When set, fylr skips this reconciliation entirely: no reverse- nested object is deleted, and any reverse-nested objects in the payload are ignored for saving — the top-level object is saved on its own. The flag additionally omits reverse-nested objects from the response.
If set, fylr does not update the opposite side of bidirectional links affected by this request. The link is still written on the object being saved.
If set, fylr does not queue search-index jobs for the saved
objects. They are written to the database but do not appear in
/api/search results until indexed by a later operation.
If set, fylr skips constraint checks while saving. This permits
objects without a pool, duplicate nested _uuid values and multiple
tags from the same tag group. Intended for migrations and bulk
imports; use with care.
If set, fylr does not run db_pre_save plugin callbacks for this
request. Requires the system.root permission.
If set, fylr does not write entries to the event log for the saved
objects. Requires the system.root permission.
Confirmation token for a workflow transition that requires explicit
confirmation. When a transition needs confirmation, fylr answers
with a 202 response describing it; resend the request with this
parameter set to the value taken from that response.
Set to yes to confirm that the requesting user accepts losing their
own access to an object as a result of the save, for example after
changing its _acl or owner. Without this confirmation fylr
answers with a 202 response instead of saving.
Combined confirmation that acknowledges both an ACL revocation and a
workflow transition in a single request. The value has the form
yes:<token>, where <token> is the confirmTransition value. Use
this when one save triggers both confirmations at once.
Decides what happens to the pool of reverse objects when the pool of the top level object changes.
reverse_pool_changed_always: move all reverse objects into the new pool.reverse_pool_changed_never: leave reverse objects in their current pool. When omitted, the mode configured on the mask applies. If that mode asks for a decision, fylr answers with a202response and expects the request to be resent with this parameter.
The access token in form of Bearer <token>. You can also use authorization
which does the same. authorization is looked at first.
The access token in form of Bearer <token>.
A fylr object as exchanged with the /db/{objecttype} endpoint. Every
object carries the system fields below. The content fields live in a nested
object whose key is the object type name; which fields are present depends on
the object type and the _mask. The object-type-specific sections of this
documentation describe those fields concretely.
Name of the object type. Matches {objecttype} in the URL.
Name of the mask that shapes the object. The mask selects which fields are present and whether each is writable or read-only.
Instance-wide unique ID of the object. Settable while the object is version 1 (new), immutable afterwards.
Globally unique object ID: the _system_object_id followed by
@<database name>.
System-wide unique identifier for the object.
The datetime the object was created.
The objects were created or updated successfully. The response is an array of the stored objects.
A fylr object as exchanged with the /db/{objecttype} endpoint. Every
object carries the system fields below. The content fields live in a nested
object whose key is the object type name; which fields are present depends on
the object type and the _mask. The object-type-specific sections of this
documentation describe those fields concretely.
Name of the object type. Matches {objecttype} in the URL.
Name of the mask that shapes the object. The mask selects which fields are present and whether each is writable or read-only.
Instance-wide unique ID of the object. Settable while the object is version 1 (new), immutable afterwards.
Globally unique object ID: the _system_object_id followed by
@<database name>.
System-wide unique identifier for the object.
The datetime the object was created.
The save cannot be completed until the client confirms a decision. The
body is a response_202: a list of tasks, each with a title, a
message, optional form fields and buttons. A button or form
option carries, in its name and value, the query parameter to add
when re-sending the same request. The cases here:
- The save would remove your own access — it changes the
object's
_aclor owner so the requesting user could no longer read or write it. Re-send withrevoke=yes. - A workflow transition needs confirmation — re-send with
confirmTransition=<value>, taking<value>from the task. - Reverse-nested objects would change pool and the mask leaves
the choice to the client — the task offers a
reverse_pool_changed_modeoption; re-send withreverse_pool_changed_mode=reverse_pool_changed_alwaysor=reverse_pool_changed_never.
If one save raises both the access and the transition confirmation,
re-send with the combined revoke:confirmTransition=yes:<value>.
The save request could not be processed. The code field of the
response identifies which validation rejected the request. The
schema below lists the most common codes and shows a concrete
example.
No authenticated user. The request must carry a valid access token.
The requesting user is not allowed to perform the operation — they lack a required object permission or system right.
An object affected by the request is locked by a concurrent write operation. Retry once the lock is released.
DELETE /db/{objecttype} — Delete objects of any object type.
DELETE /db/{objecttype} — Delete objects of any object type.Delete objects. Replace {objecttype} in the URL with the name of an
object type from this instance's datamodel.
The request body is an array of [object_id, version, comment] triples.
When a deleted object is still linked from other objects, delete_policy
decides what happens to those links; without it fylr answers with a
202 describing the choices.
Differs from easydb 5: deleting an object that is still referenced from
another object is resolved through the delete_policy parameter (with a
202 describing the choices when it is omitted). easydb 5 has no
delete_policy and instead rejects the deletion with HTTP 409.
Access token in the Authorization header:
Authorization: Bearer <token>.
Name of the object type, as defined in the instance's datamodel.
Decides what happens to objects and links affected by the deletion.
remove: also delete objects that link to a deleted object.setnull: keep the linking objects but clear their link.create_collection: collect the affected objects in a new collection instead of deleting them.undelete: restore previously deleted objects.purge: permanently remove objects from the trash. When omitted, fylr answers with a202response describing the choices instead of deleting anything.
Confirmation token for a workflow transition triggered by the
deletion. Resend the request with the value taken from the 202
response.
The access token in form of Bearer <token>. You can also use authorization
which does the same. authorization is looked at first.
The access token in form of Bearer <token>.
A triple of object ID (integer), version (integer) and an
optional deletion comment (string or null).
Triple element: object ID and version are integers, the
trailing comment is a string or null.
The objects were deleted. The response summarises which objects were removed and which links were cleared.
The delete_policy that was applied.
System object IDs of the objects that were removed.
System object IDs of objects whose link to a removed object was cleared.
With delete_policy=create_collection, the ID of the
top-level collection created for the affected objects.
The deletion cannot be completed until the client confirms a decision.
The body is a response_202: a list of tasks, each with a title,
a message, optional form fields and buttons; a form option or
button supplies, in its name and value, the query parameter to add
when re-sending the request. The cases here:
- No
delete_policywas given and the objects are still linked from others — the task offers adelete_policychoice:remove(also delete the linking objects),setnull(keep them but clear their link) orcreate_collection(collect the affected objects instead of deleting them). Re-send withdelete_policy=<choice>. - A workflow transition needs confirmation — re-send with
confirmTransition=<value>; adelete_policyalready chosen is carried over automatically.
The delete request could not be processed. The code field of the
response identifies which validation rejected the request.
No authenticated user. The request must carry a valid access token.
The requesting user is not allowed to perform the operation — they lack a required object permission or system right.
An object affected by the request is locked by a concurrent write operation. Retry once the lock is released.
GET /db/{objecttype}/{mask}/{objectId} — Read a single object of any object type.
GET /db/{objecttype}/{mask}/{objectId} — Read a single object of any object type.Load one object. Replace {objecttype} with an object type from the
datamodel and {mask} with one of its masks.
objectId is the object's _id. The system_object_id and
global_object_id addressing forms (with the ID in a further path
segment) apply here as well.
The response is always an array: empty when no object matches, and with
more than one entry when all_versions is set.
Access token in the Authorization header:
Authorization: Bearer <token>.
Name of the object type, as defined in the instance's datamodel.
Name of the mask that shapes the object. The mask decides which fields are present and whether each field is writable or read-only.
The _id of the object to load. Alternatively pass system_object_id or
global_object_id here and supply the actual ID in a following path segment.
Render format for the objects returned in the response.
Differs from easydb 5: fylr additionally offers
standard_extended, long_inheritance and full_inheritance. easydb
5 documents only short, standard, long and full.
fullPossible values: Number of days the signed file URLs contained in the response stay valid. If omitted, the expiry configured for the instance is used.
If set, fylr does not load and return reverse-nested objects in the response. Speeds up the response when the client does not need the nested reverse objects.
If set, fylr returns every stored version of the matched objects instead of only the latest one.
Load this specific _version of the object instead of the latest
one.
If set, linked objects are loaded in their latest version even when a
historic version of the top level object is requested.
Controls whether linked objects are embedded into the returned objects rather than only referenced.
nonePossible values: Maximum depth up to which linked objects are embedded when
merge_linked_objects is used.
The access token in form of Bearer <token>. You can also use authorization
which does the same. authorization is looked at first.
The access token in form of Bearer <token>.
The matched object. The response is an array and is empty when no object matches.
A fylr object as exchanged with the /db/{objecttype} endpoint. Every
object carries the system fields below. The content fields live in a nested
object whose key is the object type name; which fields are present depends on
the object type and the _mask. The object-type-specific sections of this
documentation describe those fields concretely.
Name of the object type. Matches {objecttype} in the URL.
Name of the mask that shapes the object. The mask selects which fields are present and whether each is writable or read-only.
Instance-wide unique ID of the object. Settable while the object is version 1 (new), immutable afterwards.
Globally unique object ID: the _system_object_id followed by
@<database name>.
System-wide unique identifier for the object.
The datetime the object was created.
The request could not be processed — typically an unknown object type or mask, or an invalid query parameter.
No authenticated user. The request must carry a valid access token.
The requesting user is not allowed to perform the operation — they lack a required object permission or system right.
GET /db/{objecttype}/{mask}/list — List objects of any object type.
GET /db/{objecttype}/{mask}/list — List objects of any object type.Load a page of objects. Replace {objecttype} with an object type from
the datamodel and {mask} with one of its masks. Use limit and
offset to page through the result.
Only objects the requesting user is allowed to read are returned, so a
page can contain fewer than limit entries.
Access token in the Authorization header:
Authorization: Bearer <token>.
Name of the object type, as defined in the instance's datamodel.
Name of the mask that shapes the object. The mask decides which fields are present and whether each field is writable or read-only.
Render format for the objects returned in the response.
Differs from easydb 5: fylr additionally offers
standard_extended, long_inheritance and full_inheritance. easydb
5 documents only short, standard, long and full.
fullPossible values: Number of days the signed file URLs contained in the response stay valid. If omitted, the expiry configured for the instance is used.
If set, fylr does not load and return reverse-nested objects in the response. Speeds up the response when the client does not need the nested reverse objects.
If set, fylr returns every stored version of the matched objects instead of only the latest one.
Maximum number of objects to return.
1000Number of objects to skip before the first returned object.
0The access token in form of Bearer <token>. You can also use authorization
which does the same. authorization is looked at first.
The access token in form of Bearer <token>.
A page of objects, rendered in the requested format.
A fylr object as exchanged with the /db/{objecttype} endpoint. Every
object carries the system fields below. The content fields live in a nested
object whose key is the object type name; which fields are present depends on
the object type and the _mask. The object-type-specific sections of this
documentation describe those fields concretely.
Name of the object type. Matches {objecttype} in the URL.
Name of the mask that shapes the object. The mask selects which fields are present and whether each is writable or read-only.
Instance-wide unique ID of the object. Settable while the object is version 1 (new), immutable afterwards.
Globally unique object ID: the _system_object_id followed by
@<database name>.
System-wide unique identifier for the object.
The datetime the object was created.
The request could not be processed — typically an unknown object type or mask, or an invalid query parameter.
No authenticated user. The request must carry a valid access token.
The requesting user is not allowed to perform the operation — they lack a required object permission or system right.
Last updated