/api/v1/pool
Manage pools — fylr's hierarchical containers for storage, permissions and metadata defaults. Pools form a tree; each pool can inherit ACL items and configuration from its parent.
Differs from easydb 5: a save that touches collection ACLs is confirmed with the allow_invalid_acl / background_invalid_acl / background_invalid_acl_timelimit query parameters instead of easydb 5's single collection_rights_policy parameter.
Differs from easydb 5: there is no separate system.rights_management right for updating rights-management attributes on the root pool — every save is gated on system.poolmanager (or system.root) plus the per-pool bag_* rights. (easydb 5 required system.rights_management for root-pool rights changes.)
GET /pool — List all pools visible to the authenticated user.
Access token in the Authorization header:
Authorization: Bearer <token>.
Maximum number of pools to return. Defaults to 1000. The
server pages internally and returns at most limit pools the
session is allowed to read.
1000Number of pools to skip before collecting results. Defaults to
0.
0Array of all pools the current session can see.
A storage pool — fylr's hierarchical container for objects, ACL rules, tag policy and per-objecttype default masks.
Fixed marker identifying this object as a pool.
Read-only flag indicating that at least one sub-pool exists. Useful for tree-view rendering without an extra query.
If true, this pool's ACL is private — it does not inherit ACL items from its parent.
If true, this pool's transitions are private — sub-pools do not inherit them.
If true, this pool's tags are private — sub-pools do not inherit them.
0 for root pools, +1 for every descent into the tree.
No authenticated user. The request must carry a valid access token.
[
{
"_basetype": "pool",
"pool": {
"_version": 1,
"lookup:_id_parent": {
"reference": "system:root"
},
"reference": "testpool",
"comment": "horst",
"name": {
"de-DE": "Testpool [DE]",
"en-US": "Testpool [EN]"
}
}
}
]POST /pool — Create or update one or more pools.
Access token in the Authorization header:
Authorization: Bearer <token>.
Answer to the file-resync 202 prompt. When a save changes a
pool's watermark or caption, the originals in that pool must
be re-rendered. Resend with confirm=resync to schedule the
re-sync, or confirm=skip to save without re-rendering.
Omitting it on the first request triggers the 202 prompt.
After the pool change, fylr re-checks the ACL validity of
collections affected by the pool's ACL. With
allow_invalid_acl=true the save is accepted even if some
collections end up with an invalid ACL; with the default
false such a case is returned as an error.
falseIf true, the post-save collection-ACL re-check is queued as
a background task instead of running inline, and the request
returns without waiting for it.
falseGo duration string (e.g. 30s) bounding the inline
collection-ACL re-check. Defaults to 30s. If the check
exceeds it, the response is a 202 offering to continue the
check in the background (background_invalid_acl=true).
A storage pool — fylr's hierarchical container for objects, ACL rules, tag policy and per-objecttype default masks.
Fixed marker identifying this object as a pool.
Read-only flag indicating that at least one sub-pool exists. Useful for tree-view rendering without an extra query.
If true, this pool's ACL is private — it does not inherit ACL items from its parent.
If true, this pool's transitions are private — sub-pools do not inherit them.
If true, this pool's tags are private — sub-pools do not inherit them.
0 for root pools, +1 for every descent into the tree.
The pools were saved.
A storage pool — fylr's hierarchical container for objects, ACL rules, tag policy and per-objecttype default masks.
Fixed marker identifying this object as a pool.
Read-only flag indicating that at least one sub-pool exists. Useful for tree-view rendering without an extra query.
If true, this pool's ACL is private — it does not inherit ACL items from its parent.
If true, this pool's transitions are private — sub-pools do not inherit them.
If true, this pool's tags are private — sub-pools do not inherit them.
0 for root pools, +1 for every descent into the tree.
A confirmation is required before the save can complete. Two
cases: (a) a watermark or caption change needs originals to be
re-rendered — resend with confirm=resync or confirm=skip;
(b) the post-save collection-ACL re-check exceeded its time
limit — resend with background_invalid_acl=true to finish it
in the background.
The request could not be processed. Triggers include an
invalid payload, the instance being in read-only mode (code
ReadOnlyMode), a save of a non-root pool without a parent
(code PoolNeedsParent), and — on DELETE — a pool that
still holds objects (code PoolNotEmpty).
No authenticated user. The request must carry a valid access token.
The request is forbidden. For POST/PUT, DELETE and /stats
the user must hold the system.poolmanager system right (or
system.root); otherwise the response is code
SystemRightRequired with parameters.rights naming the
required right(s). For reads (GET /pool/{poolID}, /stats)
and the per-pool BAG checks on save and delete, the relevant
pool _acl grant is missing (code RightRequired, with
parameters.right naming the missing right, e.g. bag_read,
bag_create, bag_write, bag_acl, bag_delete).
[
{
"_basetype": "pool",
"pool": {
"_version": 1,
"lookup:_id_parent": {
"reference": "system:root"
},
"reference": "testpool",
"comment": "horst",
"name": {
"de-DE": "Testpool [DE]",
"en-US": "Testpool [EN]"
}
}
}
]PUT /pool — Create or update one or more pools (alias for POST).
Access token in the Authorization header:
Authorization: Bearer <token>.
Answer to the file-resync 202 prompt. When a save changes a
pool's watermark or caption, the originals in that pool must
be re-rendered. Resend with confirm=resync to schedule the
re-sync, or confirm=skip to save without re-rendering.
Omitting it on the first request triggers the 202 prompt.
After the pool change, fylr re-checks the ACL validity of
collections affected by the pool's ACL. With
allow_invalid_acl=true the save is accepted even if some
collections end up with an invalid ACL; with the default
false such a case is returned as an error.
falseIf true, the post-save collection-ACL re-check is queued as
a background task instead of running inline, and the request
returns without waiting for it.
falseGo duration string (e.g. 30s) bounding the inline
collection-ACL re-check. Defaults to 30s. If the check
exceeds it, the response is a 202 offering to continue the
check in the background (background_invalid_acl=true).
A storage pool — fylr's hierarchical container for objects, ACL rules, tag policy and per-objecttype default masks.
Fixed marker identifying this object as a pool.
Read-only flag indicating that at least one sub-pool exists. Useful for tree-view rendering without an extra query.
If true, this pool's ACL is private — it does not inherit ACL items from its parent.
If true, this pool's transitions are private — sub-pools do not inherit them.
If true, this pool's tags are private — sub-pools do not inherit them.
0 for root pools, +1 for every descent into the tree.
The pools were saved.
A storage pool — fylr's hierarchical container for objects, ACL rules, tag policy and per-objecttype default masks.
Fixed marker identifying this object as a pool.
Read-only flag indicating that at least one sub-pool exists. Useful for tree-view rendering without an extra query.
If true, this pool's ACL is private — it does not inherit ACL items from its parent.
If true, this pool's transitions are private — sub-pools do not inherit them.
If true, this pool's tags are private — sub-pools do not inherit them.
0 for root pools, +1 for every descent into the tree.
A confirmation is required before the save can complete. Two
cases: (a) a watermark or caption change needs originals to be
re-rendered — resend with confirm=resync or confirm=skip;
(b) the post-save collection-ACL re-check exceeded its time
limit — resend with background_invalid_acl=true to finish it
in the background.
The request could not be processed. Triggers include an
invalid payload, the instance being in read-only mode (code
ReadOnlyMode), a save of a non-root pool without a parent
(code PoolNeedsParent), and — on DELETE — a pool that
still holds objects (code PoolNotEmpty).
No authenticated user. The request must carry a valid access token.
The request is forbidden. For POST/PUT, DELETE and /stats
the user must hold the system.poolmanager system right (or
system.root); otherwise the response is code
SystemRightRequired with parameters.rights naming the
required right(s). For reads (GET /pool/{poolID}, /stats)
and the per-pool BAG checks on save and delete, the relevant
pool _acl grant is missing (code RightRequired, with
parameters.right naming the missing right, e.g. bag_read,
bag_create, bag_write, bag_acl, bag_delete).
[
{
"_basetype": "pool",
"pool": {
"_version": 1,
"lookup:_id_parent": {
"reference": "system:root"
},
"reference": "testpool",
"comment": "horst",
"name": {
"de-DE": "Testpool [DE]",
"en-US": "Testpool [EN]"
}
}
}
]GET /pool/{poolID} — Retrieve a single pool by id.
Access token in the Authorization header:
Authorization: Bearer <token>.
The pool's _id.
A single-element array containing the requested pool. The handler always serialises the pool list as a JSON array, even for one pool.
A storage pool — fylr's hierarchical container for objects, ACL rules, tag policy and per-objecttype default masks.
Fixed marker identifying this object as a pool.
Read-only flag indicating that at least one sub-pool exists. Useful for tree-view rendering without an extra query.
If true, this pool's ACL is private — it does not inherit ACL items from its parent.
If true, this pool's transitions are private — sub-pools do not inherit them.
If true, this pool's tags are private — sub-pools do not inherit them.
0 for root pools, +1 for every descent into the tree.
No authenticated user. The request must carry a valid access token.
The request is forbidden. For POST/PUT, DELETE and /stats
the user must hold the system.poolmanager system right (or
system.root); otherwise the response is code
SystemRightRequired with parameters.rights naming the
required right(s). For reads (GET /pool/{poolID}, /stats)
and the per-pool BAG checks on save and delete, the relevant
pool _acl grant is missing (code RightRequired, with
parameters.right naming the missing right, e.g. bag_read,
bag_create, bag_write, bag_acl, bag_delete).
[
{
"_basetype": "pool",
"pool": {
"_version": 1,
"lookup:_id_parent": {
"reference": "system:root"
},
"reference": "testpool",
"comment": "horst",
"name": {
"de-DE": "Testpool [DE]",
"en-US": "Testpool [EN]"
}
}
}
]DELETE /pool/{poolID} — Delete a pool by id.
Deletes the pool. The session must hold the system.poolmanager
system right and the bag_delete right on the pool. Pools that
still contain objects (directly or via subpools) cannot be deleted
— the response surfaces this as a 400 with code PoolNotEmpty.
Differs from easydb 5: an unknown pool id is reported as 404
with code ResourceNotFound. (easydb 5 returns a 400 "pool id
not found" error.)
Access token in the Authorization header:
Authorization: Bearer <token>.
The pool's _id.
The pool was deleted.
The request could not be processed. Triggers include an
invalid payload, the instance being in read-only mode (code
ReadOnlyMode), a save of a non-root pool without a parent
(code PoolNeedsParent), and — on DELETE — a pool that
still holds objects (code PoolNotEmpty).
No authenticated user. The request must carry a valid access token.
The request is forbidden. For POST/PUT, DELETE and /stats
the user must hold the system.poolmanager system right (or
system.root); otherwise the response is code
SystemRightRequired with parameters.rights naming the
required right(s). For reads (GET /pool/{poolID}, /stats)
and the per-pool BAG checks on save and delete, the relevant
pool _acl grant is missing (code RightRequired, with
parameters.right naming the missing right, e.g. bag_read,
bag_create, bag_write, bag_acl, bag_delete).
The pool id in the URL does not match any stored pool. The
response carries code: ResourceNotFound with
parameters.resource = Pool <id>.
{
"status": {
"acknowledged": "ok"
}
}GET /pool/{poolID}/stats — Statistics for a single pool.
Returns file/asset statistics (counts and storage sizes of
originals — latest, history and deleted) for the pool. Requires
the system.poolmanager system right and bag_read on the pool.
With include_subpools=true the figures roll up the whole
sub-tree below the pool; otherwise only this pool.
Access token in the Authorization header:
Authorization: Bearer <token>.
The pool's _id.
If true, the counts roll up the whole sub-tree below the
requested pool. Defaults to false.
falseAsset statistics for the pool — file counts and storage
usage scoped to this pool (and, with include_subpools=true,
its transitive sub-tree).
Asset statistics for one pool — file counts and storage usage
for the objects in this pool (and, when the request set
include_subpools=true, the transitive sub-tree).
The pool this stats document is for.
RFC 3339 timestamp of when these stats were collected (for example
2024-01-01T00:00:00Z). The pool stats query is expensive, so the
result may be served from a cache window.
No authenticated user. The request must carry a valid access token.
The request is forbidden. For POST/PUT, DELETE and /stats
the user must hold the system.poolmanager system right (or
system.root); otherwise the response is code
SystemRightRequired with parameters.rights naming the
required right(s). For reads (GET /pool/{poolID}, /stats)
and the per-pool BAG checks on save and delete, the relevant
pool _acl grant is missing (code RightRequired, with
parameters.right naming the missing right, e.g. bag_read,
bag_create, bag_write, bag_acl, bag_delete).
{
"pool_id": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"files": {
"count": 1,
"size": 1,
"originals": {
"latest": {
"size": 1,
"count": 1,
"by_extension": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
},
"by_class": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
}
},
"history": {
"size": 1,
"count": 1,
"by_extension": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
},
"by_class": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
}
},
"deleted": {
"size": 1,
"count": 1,
"by_extension": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
},
"by_class": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
}
}
},
"versions": {
"latest": {
"size": 1,
"count": 1,
"by_extension": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
},
"by_class": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
}
},
"history": {
"size": 1,
"count": 1,
"by_extension": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
},
"by_class": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
}
},
"deleted": {
"size": 1,
"count": 1,
"by_extension": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
},
"by_class": {
"ANY_ADDITIONAL_PROPERTY": {
"size": 1,
"count": 1
}
}
}
}
}
}Last updated