/api/v1/system
GET /system/status — System object/index/file statistics.
GET /system/status — System object/index/file statistics.Returns counts of stored objects (per objecttype and per basetype), index-queue depth, file processing queue depth and per-index storage sizes. Used by the inspect UI's status page and by external monitoring.
The x-fylr-status response header carries the instance's
current lifecycle status word (one of startup, ready,
purge, reindex, busy) — not the build / version / capability
details.
Requires system.root.
Access token in the Authorization header:
Authorization: Bearer <token>.
Object, index and file processing statistics. Sets the
x-fylr-status response header to the current lifecycle
status word (startup, ready, purge, reindex, busy).
System statistics — per-objecttype and per-basetype object counts,
index-queue depth, file processing queues, and per-index storage
stats. Returned by GET /system/status.
Build / version / capability information is not in this body
— it travels in the x-fylr-status response header, in the form
<config>-<instance>-<version> <build_commit> plus per-component
flags (use the inspect UI's status page for the rendered view).
Sum of objects still waiting in the index queue across all types.
Number of files in the "pending" pipeline state (waiting to be processed by the execserver).
Number of files queued for processing — superset of
pending_files that includes retries.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
GET /system/errortest — Trigger a test error (for error-handling validation).
GET /system/errortest — Trigger a test error (for error-handling validation).Returns a synthetic error so clients can verify they parse fylr's
error envelope correctly. Surfaces under code: Test.
Access token in the Authorization header:
Authorization: Bearer <token>.
The synthetic error.
The synthetic error.
GET /system/openapi/spec.json — The OpenAPI specification for the v1 API (JSON).
GET /system/openapi/spec.json — The OpenAPI specification for the v1 API (JSON).Returns the same JSON spec as /inspect/apidocs/spec/spec.json,
mounted under the API surface.
Access requires the system.root right, OR the base config flag
system.openapi_spec_endpoint.active to be enabled — in which
case the endpoint is reachable without authentication.
Access token in the Authorization header:
Authorization: Bearer <token>.
The OpenAPI 3.1 document for this fylr instance, as JSON. The body is a full OpenAPI spec — too large to model inline; consume it with an OpenAPI parser.
The caller does not hold the system.root right and the base
config flag system.openapi_spec_endpoint.active is not
enabled. The response carries code: InsufficientRights.
No content
POST /system/reindex — Rebuild the search index from scratch.
POST /system/reindex — Rebuild the search index from scratch.Drops the search index into a freshly created one and triggers a full reindexing run. The reindexing work runs asynchronously on the server; the call returns as soon as the run has been started. The frontend can be blocked while the reindex is in progress so users do not see partial results.
This operation performs no rights check in the handler today.
Access token in the Authorization header:
Authorization: Bearer <token>.
If true, fylr serves a maintenance page on the frontend
until the reindex completes.
falseThe reindexing run was started.
The reindexing run was started.
POST /system/purgeall — Wipe and re-initialize the entire instance (factory reset).
POST /system/purgeall — Wipe and re-initialize the entire instance (factory reset).Drops the search index, optionally purges file storage (base config
system.purge.purge_storage), resets the database to an empty
state and re-initializes a fresh instance. This destroys all
data — it is not a cleanup of soft-deleted records. Restricted to
the system:root user and cannot be undone.
Purging must be enabled in the configuration: both the yml
fylr.allowpurge and the base config system.purge.allow_purge
must be set, otherwise the call returns code: PurgeNotAllowed.
Access token in the Authorization header:
Authorization: Bearer <token>.
Optional URL. If set, the server starts the purge in the
background and immediately responds with a 302 redirect to
this URL instead of waiting for the purge to finish.
Optional new password for the system:root user, applied
after the instance has been re-initialized.
The purge completed.
Returned when a redirect value is supplied: the purge runs in
the background and the response redirects to the given URL.
Purging is not enabled in the configuration (yml
fylr.allowpurge and base config system.purge.allow_purge).
The response carries code: PurgeNotAllowed.
No authenticated user. The request must carry a valid access token.
The caller is not allowed to purge. code: SystemRightRequired
if the user lacks system.root; code: PurgeSystemRootOnly
if the user holds system.root but is not the system:root
user.
PUT /system/backup/new — Create a new backup.
PUT /system/backup/new — Create a new backup.Starts a new backup of the database, files and configuration. The
backup runs asynchronously: the call returns the backup descriptor
with a running status immediately, and the archive is produced in
the background and stored in the configured backup location.
Requires system.backup (or system.root).
Access token in the Authorization header:
Authorization: Bearer <token>.
Options the backup was started with. Echoed back on read so clients can tell which format the produced artifact is in.
Backup format. The recognised values are configured per
instance and surface in GET /api/v1/system/backup/list;
typical values include sqlite3_db (single-file SQLite
snapshot) and pg_dump (PostgreSQL dump archive).
When true, the event log is included in the backup. When false, only the datamodel and user data are dumped — useful for migrating to a new instance without carrying the event history along.
The backup descriptor.
A backup descriptor — a record of a single backup run produced by
PUT /api/v1/system/backup/new.
Server-issued numeric id.
UTC time the backup was created.
UTC time the backup completed. Null while the backup is still running.
Current backup state — running, done, error.
The backup could not be started. code: FormatNotSupported if
the requested format is not one of the supported formats;
otherwise a generic error (code: ServerGeneric), for example
when no backup storage location is configured.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
GET /system/backup/list — List backups on file.
GET /system/backup/list — List backups on file.Requires system.backup (or system.root).
Access token in the Authorization header:
Authorization: Bearer <token>.
Array of backup descriptors.
A backup descriptor — a record of a single backup run produced by
PUT /api/v1/system/backup/new.
Server-issued numeric id.
UTC time the backup was created.
UTC time the backup completed. Null while the backup is still running.
Current backup state — running, done, error.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
GET /system/backup/{id} — Retrieve a backup descriptor.
GET /system/backup/{id} — Retrieve a backup descriptor.Requires system.backup (or system.root).
Access token in the Authorization header:
Authorization: Bearer <token>.
The backup descriptor.
A backup descriptor — a record of a single backup run produced by
PUT /api/v1/system/backup/new.
Server-issued numeric id.
UTC time the backup was created.
UTC time the backup completed. Null while the backup is still running.
Current backup state — running, done, error.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
The backup id does not exist. The response carries
code: BackupNotFound.
DELETE /system/backup/{id} — Delete a backup.
DELETE /system/backup/{id} — Delete a backup.Only a backup whose status is done or error can be deleted.
Requires system.backup (or system.root).
Access token in the Authorization header:
Authorization: Bearer <token>.
The backup was deleted.
The backup cannot be deleted in its current status (only done
or error backups can be deleted). The response carries
code: DeleteNotSupported.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
The backup id does not exist. The response carries
code: BackupNotFound.
GET /system/backup/{id}/download — Download a backup archive.
GET /system/backup/{id}/download — Download a backup archive.Requires system.backup (or system.root).
Access token in the Authorization header:
Authorization: Bearer <token>.
The backup bytes.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
The backup id does not exist. The response carries
code: BackupNotFound.
POST /system/location/new — Create a new storage location.
POST /system/location/new — Create a new storage location.Requires system.location (or system.root). The id in the
body must be 0 for a create.
Access token in the Authorization header:
Authorization: Bearer <token>.
A storage location descriptor — an external bucket where fylr
reads / writes files. Used by /api/v1/system/location* and
surfaced read-only on every file download via the
X-Fylr-Storage-Location response header.
Server-issued numeric id. On create, must be set to the same
value that appears in the URL /system/location/{id} (or
0 for POST /system/location/new).
UTC time the location was created.
Human-readable label.
Storage driver — file (local disk), s3 (AWS / S3-compatible),
or azure (Azure Blob Storage). Selects which config shape
(file / s3 / azure) is expected.
Optional bucket prefix — every key written to the location is
prepended with it. Usually ends in /.
Whether POST /api/v1/system/purgeall may delete files from
this location. Disable to keep an archival location intact.
Whether file downloads from this location may use HTTP
Location: redirects (for remote buckets with their own URL
signers).
Whether this location accepts writes. If true, new files are sent to the next writable location and only reads come from here.
Read-only connection state — connected, not accessible,
error, closed.
Read-only diagnostic message attached to a non-connected
status — usually the underlying error from the driver.
The created location.
A storage location descriptor — an external bucket where fylr
reads / writes files. Used by /api/v1/system/location* and
surfaced read-only on every file download via the
X-Fylr-Storage-Location response header.
Server-issued numeric id. On create, must be set to the same
value that appears in the URL /system/location/{id} (or
0 for POST /system/location/new).
UTC time the location was created.
Human-readable label.
Storage driver — file (local disk), s3 (AWS / S3-compatible),
or azure (Azure Blob Storage). Selects which config shape
(file / s3 / azure) is expected.
Optional bucket prefix — every key written to the location is
prepended with it. Usually ends in /.
Whether POST /api/v1/system/purgeall may delete files from
this location. Disable to keep an archival location intact.
Whether file downloads from this location may use HTTP
Location: redirects (for remote buckets with their own URL
signers).
Whether this location accepts writes. If true, new files are sent to the next writable location and only reads come from here.
Read-only connection state — connected, not accessible,
error, closed.
Read-only diagnostic message attached to a non-connected
status — usually the underlying error from the driver.
The location could not be created. code: LocationMustMatchID
if the body id does not match the create (0);
code: LocationReadOnlyCannotBeDefault if a read-only location
is configured as a default location; other validation codes
(unknown driver, missing config, ...) surface their own code.
Connection problems with the configured driver do not block the
save — the location is stored with a non-connected status.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
GET /system/location/list — List configured storage locations.
GET /system/location/list — List configured storage locations.Requires system.location, system.config, or system.root.
Access token in the Authorization header:
Authorization: Bearer <token>.
Array of locations.
A storage location descriptor — an external bucket where fylr
reads / writes files. Used by /api/v1/system/location* and
surfaced read-only on every file download via the
X-Fylr-Storage-Location response header.
Server-issued numeric id. On create, must be set to the same
value that appears in the URL /system/location/{id} (or
0 for POST /system/location/new).
UTC time the location was created.
Human-readable label.
Storage driver — file (local disk), s3 (AWS / S3-compatible),
or azure (Azure Blob Storage). Selects which config shape
(file / s3 / azure) is expected.
Optional bucket prefix — every key written to the location is
prepended with it. Usually ends in /.
Whether POST /api/v1/system/purgeall may delete files from
this location. Disable to keep an archival location intact.
Whether file downloads from this location may use HTTP
Location: redirects (for remote buckets with their own URL
signers).
Whether this location accepts writes. If true, new files are sent to the next writable location and only reads come from here.
Read-only connection state — connected, not accessible,
error, closed.
Read-only diagnostic message attached to a non-connected
status — usually the underlying error from the driver.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
GET /system/location/{id} — Retrieve a single storage location.
GET /system/location/{id} — Retrieve a single storage location.Requires system.location, system.config, or system.root.
Access token in the Authorization header:
Authorization: Bearer <token>.
The location.
A storage location descriptor — an external bucket where fylr
reads / writes files. Used by /api/v1/system/location* and
surfaced read-only on every file download via the
X-Fylr-Storage-Location response header.
Server-issued numeric id. On create, must be set to the same
value that appears in the URL /system/location/{id} (or
0 for POST /system/location/new).
UTC time the location was created.
Human-readable label.
Storage driver — file (local disk), s3 (AWS / S3-compatible),
or azure (Azure Blob Storage). Selects which config shape
(file / s3 / azure) is expected.
Optional bucket prefix — every key written to the location is
prepended with it. Usually ends in /.
Whether POST /api/v1/system/purgeall may delete files from
this location. Disable to keep an archival location intact.
Whether file downloads from this location may use HTTP
Location: redirects (for remote buckets with their own URL
signers).
Whether this location accepts writes. If true, new files are sent to the next writable location and only reads come from here.
Read-only connection state — connected, not accessible,
error, closed.
Read-only diagnostic message attached to a non-connected
status — usually the underlying error from the driver.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
No storage location with the given id is configured. The
response carries code: ResourceNotFound.
PUT /system/location/{id} — Update a storage location.
PUT /system/location/{id} — Update a storage location.Saves the storage location under the id in the path (an upsert —
the body id must equal the path id). Requires system.location
(or system.root).
Access token in the Authorization header:
Authorization: Bearer <token>.
A storage location descriptor — an external bucket where fylr
reads / writes files. Used by /api/v1/system/location* and
surfaced read-only on every file download via the
X-Fylr-Storage-Location response header.
Server-issued numeric id. On create, must be set to the same
value that appears in the URL /system/location/{id} (or
0 for POST /system/location/new).
UTC time the location was created.
Human-readable label.
Storage driver — file (local disk), s3 (AWS / S3-compatible),
or azure (Azure Blob Storage). Selects which config shape
(file / s3 / azure) is expected.
Optional bucket prefix — every key written to the location is
prepended with it. Usually ends in /.
Whether POST /api/v1/system/purgeall may delete files from
this location. Disable to keep an archival location intact.
Whether file downloads from this location may use HTTP
Location: redirects (for remote buckets with their own URL
signers).
Whether this location accepts writes. If true, new files are sent to the next writable location and only reads come from here.
Read-only connection state — connected, not accessible,
error, closed.
Read-only diagnostic message attached to a non-connected
status — usually the underlying error from the driver.
The updated location.
A storage location descriptor — an external bucket where fylr
reads / writes files. Used by /api/v1/system/location* and
surfaced read-only on every file download via the
X-Fylr-Storage-Location response header.
Server-issued numeric id. On create, must be set to the same
value that appears in the URL /system/location/{id} (or
0 for POST /system/location/new).
UTC time the location was created.
Human-readable label.
Storage driver — file (local disk), s3 (AWS / S3-compatible),
or azure (Azure Blob Storage). Selects which config shape
(file / s3 / azure) is expected.
Optional bucket prefix — every key written to the location is
prepended with it. Usually ends in /.
Whether POST /api/v1/system/purgeall may delete files from
this location. Disable to keep an archival location intact.
Whether file downloads from this location may use HTTP
Location: redirects (for remote buckets with their own URL
signers).
Whether this location accepts writes. If true, new files are sent to the next writable location and only reads come from here.
Read-only connection state — connected, not accessible,
error, closed.
Read-only diagnostic message attached to a non-connected
status — usually the underlying error from the driver.
The location could not be saved. code: LocationMustMatchID
if the body id does not match the id in the path;
code: LocationReadOnlyCannotBeDefault if a read-only
location is configured as a default location; other
validation codes surface their own code.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
DELETE /system/location/{id} — Delete a storage location.
DELETE /system/location/{id} — Delete a storage location.Requires system.location (or system.root).
Access token in the Authorization header:
Authorization: Bearer <token>.
The location was deleted. A delete for an id that is not configured also returns 200 (no row is removed).
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the system right required for
the operation (typically system.root).
Last updated