Flex Objects

Get Flex Config

{"data": {"enabled": true, "built_in_css": true, "security": {"restrict_page_frontmatter": true}, "admin_list": {"per_page": 15, "order": {"by": "updated_timestamp", "dir": "desc"}}}}

Lightweight configuration endpoint. The list of directories is returned separately by GET /flex-objects so callers that only need config stay small.

List Directories

{"data": [{"type": "contacts", "title": "Contacts", "description": "Address book", "icon": "fa-address-book", "list": {"fields": {"name": {}, "email": {}}}, "edit": {}, "search": {"fields": ["name", "email"]}, "field_types": {"name": "text", "email": "email"}, "field_options": {}, "export": {}}]}

Each entry's type is the Flex directory key you pass as {type} to the object endpoints below. Directories the user lacks list permission on are omitted from the result, as are directories whose blueprint has no admin section or sets admin.disabled. Each entry has the same fields as Get Directory Metadata.

List Blueprints

{"data": [{"url": "blueprints://flex-objects/contacts.yaml", "legacy_url": null, "type": "contacts", "title": "Contacts", "description": "Address book"}]}

legacy_url carries the pre-existing blueprint alias (when one exists) so saved settings that still reference the old form can be matched.

List Objects

{"data": [{"key": "ada", "name": "Ada Lovelace", "email": "[email protected]"}], "meta": {"pagination": {"page": 1, "per_page": 20, "total": 1, "total_pages": 1}}, "links": {"self": "https://example.com/api/v1/flex-objects/contacts?page=1&per_page=20"}}

The key on each item is the object identifier you pass as {key} to the single-object endpoints. A directory with no configured list fields returns each object's full data instead. When the directory configures a related detail list (admin.list.detail) that the user can see, each item also carries a __detail object describing the related directory, the filter that selects its records, and whether the user can edit or delete them.

Get Object

{"data": {"key": "ada", "__meta": {"type": "contacts", "key": "ada", "storageKey": "ada", "storagePath": "user-data://flex-objects/contacts/ada"}, "name": "Ada Lovelace", "email": "[email protected]"}}

Keep the returned ETag and send it back as an If-Match header when updating, so a concurrent change is detected instead of silently overwritten.

The reserved __meta object is read-only information for the admin (the object's type, key, storage key and, when known, its storage folder). It is never saved: create and update strip it from the request body.

Create Object

{"name": "Grace Hopper", "email": "[email protected]"}

{"data": {"key": "grace-hopper", "__meta": {"type": "contacts", "key": "grace-hopper", "storageKey": "grace-hopper"}, "name": "Grace Hopper", "email": "[email protected]"}}

Post to the collection address (no key segment). To attach files to the object afterwards, use the Upload Object Media endpoint below with the key returned here.

Update Object

{"email": "[email protected]"}

{"data": {"key": "grace-hopper", "__meta": {"type": "contacts", "key": "grace-hopper", "storageKey": "grace-hopper"}, "name": "Grace Hopper", "email": "[email protected]"}}

This is a partial update: fields you omit are left untouched. Use PATCH, not POST (posting to an object URL is not allowed).

If the body sends a file field (file, avatar, pagemedia, or any field with a destination) without a file it previously held, that file is deleted from the object's own folder when the object saves. Files stored in a shared destination such as media:// are only unlinked from the field and stay on disk.

Delete Object

Returns no content on success.

Export Directory

Export only works for directories whose blueprint sets admin.export.enabled; the built-in user accounts, groups and pages directories don't, and return 404. Because it returns every field of every object, it needs the directory's read permission, not just list.

The response is application/x-yaml with a filename like contacts-YYYY-MM-DD.yaml, not the standard JSON envelope.

List Object Media

{"data": [{"filename": "avatar.png", "type": "image/png", "size": 20480, "url": "/user/data/flex-objects/contacts/ada/avatar.png"}]}

Object media requires folder-based storage (one folder per object, e.g. user-data://flex-objects/contacts/{id}). Directories that keep all records in a single shared file have nowhere to store per-object files, and the endpoint returns 422.

Upload Object Media

{"data": [{"filename": "avatar.png", "url": "/user/data/flex-objects/contacts/ada/avatar.png", "type": "image/png", "size": 20480}]}

Send the file as a multipart/form-data request (set Content-Type: multipart/form-data), not JSON. Uploads are validated against Grav's dangerous-extensions list and a 64 MB size cap. Requires folder-based storage for the directory (one folder per object); directories that use single-file storage return 422.

A file field can pass its own upload settings as extra form fields: random_name, avoid_overwriting, accept and filesize (in MB). These only tighten the checks above; they can't raise the 64 MB cap.

Delete Object Media

Returns no content on success.

Get Directory Metadata

{"data": {"type": "contacts", "title": "Contacts", "description": "Address book", "icon": "fa-address-book", "list": {"fields": {"name": {}, "email": {}}}, "edit": {}, "search": {"fields": ["name", "email"]}, "field_types": {"name": "text", "email": "email"}, "field_options": {}, "export": {}}}

This is the same payload each entry of List Directories carries, fetched for a single directory. field_types and field_options let the client render typed list cells (dates as dates, choice values as their labels) instead of raw stored values.