/api/v1/objecttype
GET /objecttype — List all objecttypes in the current datamodel.
Returns every objecttype in the current datamodel as an
array of descriptors. Any authenticated user may read; the
auxiliary fields that need system.objecttypemanager are included
only when that right is held (or are dropped entirely with
format=short).
Access token in the Authorization header:
Authorization: Bearer <token>.
Set format=short to omit the auxiliary fields that require
the system.objecttypemanager right (_acl, tags,
transitions, mask / column filters, etc.). Any other value,
or omitting the parameter, returns the full descriptor. Only
short is special-cased — there is no separate long /
standard behaviour.
Array of objecttype descriptors.
An objecttype descriptor — fylr's per-record-type configuration layered on top of the datamodel definition: per-objecttype default masks, exposure flags (frontend menus, collections, facets), ACL rules, tags, transitions, mask / column filters, asset filename policy, watermark and janitor (cleanup) policy.
Returned by /api/v1/objecttype and /api/v1/objecttype/{id}. The
same shape is accepted as the request body of POST /api/v1/objecttype
(only the fields the requester is allowed to mutate are honoured).
Fixed marker identifying this object as an objecttype.
Ordered list of mask ids to prefer when rendering objects of
this type. The first entry is the default mask. null (rather
than an empty array) signals "no preference defined" — the
datamodel's standard mask is then used.
If true, transitions configured directly on this objecttype do not inherit transitions from the parent pool / global.
If true, the tag set configured on this objecttype shadows the inherited tags (does not merge with them).
No authenticated user. The request must carry a valid access token.
POST /objecttype — Create or update the settings of one or more objecttypes.
Updates the configuration of an array of objecttypes directly. The
objecttypes must already exist in the committed datamodel; this
endpoint writes their settings, not their structure. The change
takes effect immediately when the request transaction commits —
there is no schema/commit step. The user needs
system.objecttypemanager (or system.root). When the instance is
in read-only mode the request is rejected before processing (see
the 400 response).
The objecttype itself (its name, fields, hierarchy) is defined by
the datamodel, not created here — every element must carry an
existing objecttype._id, and objecttype._version must be
current + 1 (optimistic locking; a mismatch is a 400
VersionMismatch). Only the configuration fields are mutated;
fields the requester is not allowed to change are ignored. Fields
omitted from the body keep their stored value (the server reloads
the current objecttype and merges). Notable parse rules:
mapping_*fields take a mapping id or the string"none"to clear;mapping_image_import_recipe_configsmay only be set whenmapping_image_importnames a real mapping._standard_masks:nullclears the preference; a non-empty array of mask ids sets it; an empty array[]is rejected (ObjecttypeNeedsStandardMask).watermark.gravity, if present, must be one ofnw n ne w c e sw s seor empty.captionkeys must each name an existing files field that is not inside a reverse-nested and whose objecttype's pool management matches the endpoint (objecttype, not pool).janitor_policybounds must benullor>= 0.janitor_policyis only meaningful for non-pool objecttypes; for a pool objecttype it is neither stored nor returned. The key is merged from the stored value only when omitted — sendingnullexplicitly clears it.standard_numberingis accepted for compatibility but ignored (never stored, always returned empty).
The save can pause and return a 202 to ask for confirmation (see the 202 response). The query parameters below are how the client answers those confirmations: it re-sends the same request body with the matching parameter appended.
Differs from easydb 5: the 202 confirmation contract uses
confirm / allow_invalid_acl / background_invalid_acl rather
than easydb 5's collection_rights_policy.
Access token in the Authorization header:
Authorization: Bearer <token>.
Answer to the renditions-resync 202 that is raised when a
watermark or caption change requires recomputing the
renditions of already-stored files. resync recomputes them
now; skip saves without recomputing. Any other value is
rejected with a generic 400 (confirm "<value>" not supported).
Answer to the invalid-collection-ACL 202. When true, a save
whose ACL change would invalidate a collection the owner can
no longer fully grant is allowed to proceed; the affected
collections are flagged invalid_acl and sharing for them is
disabled. If the user lacks bag-acl on such a collection the
request instead fails with UrlParameterNotSupported for
allow_invalid_acl.
Answer to the ACL-revalidation timeout 202. When true, the
collection-ACL revalidation runs as an asynchronous background
task and the request returns immediately instead of completing
the check synchronously.
Overrides the synchronous time budget before the timeout 202
is offered. A Go duration string (e.g. 5s); an invalid value
surfaces as a generic 400.
An objecttype descriptor — fylr's per-record-type configuration layered on top of the datamodel definition: per-objecttype default masks, exposure flags (frontend menus, collections, facets), ACL rules, tags, transitions, mask / column filters, asset filename policy, watermark and janitor (cleanup) policy.
Returned by /api/v1/objecttype and /api/v1/objecttype/{id}. The
same shape is accepted as the request body of POST /api/v1/objecttype
(only the fields the requester is allowed to mutate are honoured).
Fixed marker identifying this object as an objecttype.
Ordered list of mask ids to prefer when rendering objects of
this type. The first entry is the default mask. null (rather
than an empty array) signals "no preference defined" — the
datamodel's standard mask is then used.
If true, transitions configured directly on this objecttype do not inherit transitions from the parent pool / global.
If true, the tag set configured on this objecttype shadows the inherited tags (does not merge with them).
The objecttypes were saved. The body echoes the saved
descriptors (with _acl, tags, transitions and mask filters
included). The X-Fylr-Cache-ID response header carries the
new datamodel cache id so clients can invalidate caches.
The save needs confirmation before it can complete. Resubmit
the identical request with the query parameter named by the
task's form option or button appended — for example
allow_invalid_acl=true, background_invalid_acl=true, or
confirm=resync / confirm=skip.
The request could not be processed. All errors below are
realm: api, statuscode: 400. The objecttype-specific codes
(package: objecttype) are UnknownField /
UnsupportedFieldType, both raised while resolving an
_export_asset_filenames template against the datamodel.
The body parse and the ApiToObject validation add several
package: ferrors codes:
ReadOnlyMode— the instance is in read-only mode; the request is rejected before any processing (messageRead-only mode is enabled.).VersionMismatch— a submitted objecttype's_versionis notcurrent + 1.parameters.got/parameters.expectedcarry the values.ObjecttypeNeedsStandardMask—_standard_maskswas sent as an empty array ([]); sendnullto clear the preference instead.parameters.namecarries the objecttype name.UrlParameterNotSupported—allow_invalid_acl=truewas sent but the user lacksbag-aclon an affected collection.parameters.paramisallow_invalid_acl.
Generic 400s (code: ServerGeneric or a bare message) also
surface here for: an unsupported confirm value (confirm "<value>" not supported); an unknown _standard_masks /
_maskfilters mask id (Objecttype: Mask <id> not found in Datamodel); a watermark.gravity outside the allowed set
(watermark.gravity "<value>" not supported); an out-of-range
janitor_policy bound (a negative value;
janitor_policy.file_link_delete.keep_days_history_versions must be null or > 0 and the analogous keep_count /
min_object_deleted_days messages); a bad caption
(caption "<field>": field not found, ... must not be inside a reverse nested, ... is not of type "file", or a
pool-management mismatch); recipe configs set while
mapping_image_import is "none" (mapping recipe configs can only be set for a specific mapping); own transitions / tags on
an objecttype whose pool does not allow them (Objecttype "<name>" cannot have own transitions / ... own tags); a bad
background_invalid_acl_timelimit duration. Datamodel-validation,
save-pipeline and DB-driver errors (e.g.
DatabaseUniqueKeyViolation) can appear too. The code enum
on the schema lists only the two objecttype codes; it is not
exhaustive.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (system.objecttypemanager, or system.root).
The write could not acquire a database lock because a
concurrent write is touching the same rows (PostgreSQL
55P03). The transaction is rolled back and the error is
surfaced as code: DatabaseLockError, package: ferrors,
statuscode: 423. Retry the identical request once the
conflicting write has finished.
GET /objecttype/{id} — Retrieve a single objecttype.
Loads one objecttype by numeric id and returns it wrapped in a
one-element array (the descriptor is the only array entry — the
response is not a bare object).
Access token in the Authorization header:
Authorization: Bearer <token>.
The numeric id of the objecttype. The path segment must be a
positive integer (route pattern [1-9][0-9]*); name-based
lookup is not supported on this endpoint.
Set format=short to omit the auxiliary fields that require
the system.objecttypemanager right (_acl, tags,
transitions, mask / column filters, etc.). Any other value,
or omitting the parameter, returns the full descriptor. Only
short is special-cased — there is no separate long /
standard behaviour.
A one-element array containing the objecttype descriptor.
An objecttype descriptor — fylr's per-record-type configuration layered on top of the datamodel definition: per-objecttype default masks, exposure flags (frontend menus, collections, facets), ACL rules, tags, transitions, mask / column filters, asset filename policy, watermark and janitor (cleanup) policy.
Returned by /api/v1/objecttype and /api/v1/objecttype/{id}. The
same shape is accepted as the request body of POST /api/v1/objecttype
(only the fields the requester is allowed to mutate are honoured).
Fixed marker identifying this object as an objecttype.
Ordered list of mask ids to prefer when rendering objects of
this type. The first entry is the default mask. null (rather
than an empty array) signals "no preference defined" — the
datamodel's standard mask is then used.
If true, transitions configured directly on this objecttype do not inherit transitions from the parent pool / global.
If true, the tag set configured on this objecttype shadows the inherited tags (does not merge with them).
The numeric id in the URL does not match any objecttype in
the current datamodel. The load fails and is reported as a
generic server error (code: ServerGeneric, package: ferrors, statuscode: 400) with a message of the form
Server error occurred: objecttype.LoadById: Error loading: ObjecttypeList.Load: Not all objecttypes found in DB — there
is no structured 404 for an unknown id on this endpoint.
No authenticated user. The request must carry a valid access token.
GET /objecttype/{id}/stats — Asset statistics for an objecttype.
Aggregates, in SQL, the originals and their renditions across all
latest / history / deleted objects of the type, bucketing by file
class and extension. Requires the system.objecttypemanager right
(or system.root).
Access token in the Authorization header:
Authorization: Bearer <token>.
The numeric id of the objecttype (positive integer; route
pattern [1-9][0-9]*). Name-based lookup is not supported.
Asset statistics for the objecttype — file counts and storage usage rolled up across every object of the type.
Asset statistics for one objecttype — the rolled-up file counts and storage usage across every object of the type.
The numeric id in the URL does not match any objecttype in
the current datamodel. The load fails and is reported as a
generic server error (code: ServerGeneric, package: ferrors, statuscode: 400) with a message of the form
Server error occurred: objecttype.LoadById: Error loading: ObjecttypeList.Load: Not all objecttypes found in DB — there
is no structured 404 for an unknown id on this endpoint.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (system.objecttypemanager, or system.root).
Last updated