/api/v1/event

Read, write and subscribe to events. fylr writes events for many server-side mutations (object insert/update, collection changes, file deletes, email sends, ...). This endpoint exposes the event log.

POST /event — Write a single user event.

Write a single user event.

post

Allows clients to log user events into the event stream. Any authenticated user may write event types in the FRONTEND and PLUGIN groups (e.g. SEARCH, DETAIL_VIEW, FRONTEND_ERROR). Writing event types in any other group (ADMIN, DOWNLOAD, EXPORT, INDEX, LOGIN_LOGOUT, SYSTEM, TASK, UPLOAD) requires system.root together with skip_constraints=true (see the skip_constraints parameter); a type unknown to the server is always rejected with code: EventTypeNotAllowed. Unlike the other event write operations, POST /event is permitted while the instance is in read-only mode.

Differs from easydb 5: easydb 5 lets a client insert only SEARCH and DETAIL_VIEW, and only when the matching base config (system.log.search / system.log.detail_view) is enabled. fylr allows the whole FRONTEND group (SEARCH, DETAIL_VIEW, FRONTEND_ERROR, ASSET_DOWNLOAD_CONFIRMATION_MESSAGE) and the PLUGIN group with no base-config gate, plus all other known groups via system.root + skip_constraints.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

backgroundbooleanOptional

If true, the event is saved asynchronously: the request returns {"background": "ok"} immediately and per-event validation errors (e.g. a disallowed type) are not reported in the response.

skip_constraintsbooleanOptional

If true, all other known event groups (ADMIN, DOWNLOAD, EXPORT, INDEX, LOGIN_LOGOUT, SYSTEM, TASK, UPLOAD) may also be written — not just the FRONTEND/PLUGIN user types — and a top-level user object is accepted on the event. Requires system.root; a non-root caller that sets it receives a 400 ServerGeneric error.

Body

application/json

An event record. fylr writes events for almost every server-side mutation (object insert/update, collection changes, ACL changes, email sends, login, ...).

_basetypestring · enumRequired

Fixed marker identifying this object as an event.

Possible values:

Responses

200

For a synchronous write the stored event is echoed as an EventApi. With background=true the body is {"background":"ok"}.

application/json

Response of POST /event. For a synchronous write this is the stored event (EventApi). With background=true the body is the acknowledgement object {"background": "ok"} and the event is saved asynchronously.

or

400

The request could not be processed. Possible code values: EventTypeNotAllowed (the payload's type is unknown, or is not a FRONTEND/PLUGIN user type and was not unlocked with root + skip_constraints), ServerGeneric (invalid JSON body, an unparseable query filter such as id/sort, a non-root caller passing skip_constraints, or an event carrying a user/user_id without skip_constraints), or ReadOnlyMode (the instance is in read-only mode; affects the write/delete operations only, not POST /event).

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

{
  "_basetype": "event",
  "event": {
    "_id": 1,
    "type": "text",
    "object_id": 1,
    "object_version": 1,
    "global_object_id": "text",
    "system_object_id": 1,
    "schema": "text",
    "basetype": "text",
    "objecttype": "text",
    "timestamp": "2026-08-11T20:24:35.400Z",
    "pollable": true,
    "info": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "remote_addr": "text",
    "user_generated_displayname": "text"
  },
  "user": {
    "_basetype": "user",
    "_owner": true,
    "_pool_contact": true,
    "user": {
      "_id": 1,
      "lookup:_id": {
        "reference": "text"
      },
      "_generated_displayname": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "group": {
      "_id": 1,
      "lookup:_id": {
        "reference": "text"
      },
      "_generated_displayname": "text"
    }
  }
}

GET /event/poll/{fromEventId} — Fetch pollable events newer than an event id.

Fetch pollable events newer than an event id.

get

Runs a single query for pollable events with _id strictly greater than fromEventId (ordered by _id ascending, up to limit rows) and returns immediately; the array may be empty. This is a one-shot poll, not a blocking long-poll — clients repeat the call with the highest _id they have seen. For a continuous push use GET /event/stream.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

fromEventIdinteger · int64Required

The last event id the caller has seen. Use 0 to poll from the very beginning of the pollable event log.

Query parameters

limitinteger · int64 · min: 1 · max: 1000Optional

Maximum number of events to return in this response. Default 25; values <= 0 or > 1000 are clamped to 1000.

Default: 25

Responses

200

Array of new events.

application/json

An event record. fylr writes events for almost every server-side mutation (object insert/update, collection changes, ACL changes, email sends, login, ...).

_basetypestring · enumRequired

Fixed marker identifying this object as an event.

Possible values:

401

No authenticated user. The request must carry a valid access token.

application/json

[
  {
    "_basetype": "event",
    "event": {
      "_id": 1,
      "type": "text",
      "object_id": 1,
      "object_version": 1,
      "global_object_id": "text",
      "system_object_id": 1,
      "schema": "text",
      "basetype": "text",
      "objecttype": "text",
      "timestamp": "2026-08-11T20:24:35.400Z",
      "pollable": true,
      "info": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "remote_addr": "text",
      "user_generated_displayname": "text"
    },
    "user": {
      "_basetype": "user",
      "_owner": true,
      "_pool_contact": true,
      "user": {
        "_id": 1,
        "lookup:_id": {
          "reference": "text"
        },
        "_generated_displayname": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "group": {
        "_id": 1,
        "lookup:_id": {
          "reference": "text"
        },
        "_generated_displayname": "text"
      }
    }
  }
]

GET /event/stream — WebSocket stream of new events.

WebSocket stream of new events.

get

Upgrades the connection to a WebSocket (the handler calls the gorilla/websocket upgrader) and pushes new pollable events as they happen. Each event is sent as one JSON text frame carrying the EventApi object. The client should connect with the ws:///wss:// scheme; any inbound message from the client is discarded.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Responses

101

The connection was upgraded to a WebSocket. New events follow as JSON text frames (one EventApi per frame) until the socket is closed.

No content

401

No authenticated user. The request must carry a valid access token.

application/json

No content

GET /event/{eventId} — Retrieve a single event by id.

Retrieve a single event by id.

get

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

eventIdinteger · int64Required

The event's _id.

Responses

200

The event.

application/json

An event record. fylr writes events for almost every server-side mutation (object insert/update, collection changes, ACL changes, email sends, login, ...).

_basetypestring · enumRequired

Fixed marker identifying this object as an event.

Possible values:

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system right required for this operation: system.api.event[get] for reads (GET /event/{eventId}, GET /event/list) or system.api.event[delete] for deletes (DELETE /event/{eventId}, DELETE /event/list). system.root always suffices. There is no per-object ACL on events.

application/json

404

No stored event has the id given in the URL. The response carries code: EventNotFound.

application/json

{
  "_basetype": "event",
  "event": {
    "_id": 1,
    "type": "text",
    "object_id": 1,
    "object_version": 1,
    "global_object_id": "text",
    "system_object_id": 1,
    "schema": "text",
    "basetype": "text",
    "objecttype": "text",
    "timestamp": "2026-08-11T20:24:35.400Z",
    "pollable": true,
    "info": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "remote_addr": "text",
    "user_generated_displayname": "text"
  },
  "user": {
    "_basetype": "user",
    "_owner": true,
    "_pool_contact": true,
    "user": {
      "_id": 1,
      "lookup:_id": {
        "reference": "text"
      },
      "_generated_displayname": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "group": {
      "_id": 1,
      "lookup:_id": {
        "reference": "text"
      },
      "_generated_displayname": "text"
    }
  }
}

DELETE /event/{eventId} — Delete a single event by id.

Delete a single event by id.

delete

Requires the system.api.event[delete] system right (or system.root). Rejected with 400 ReadOnlyMode while the instance is in read-only mode.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

eventIdinteger · int64Required

Responses

200

The event was deleted.

application/json

400

The request could not be processed. Possible code values: EventTypeNotAllowed (the payload's type is unknown, or is not a FRONTEND/PLUGIN user type and was not unlocked with root + skip_constraints), ServerGeneric (invalid JSON body, an unparseable query filter such as id/sort, a non-root caller passing skip_constraints, or an event carrying a user/user_id without skip_constraints), or ReadOnlyMode (the instance is in read-only mode; affects the write/delete operations only, not POST /event).

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system right required for this operation: system.api.event[get] for reads (GET /event/{eventId}, GET /event/list) or system.api.event[delete] for deletes (DELETE /event/{eventId}, DELETE /event/list). system.root always suffices. There is no per-object ACL on events.

application/json

404

No stored event has the id given in the URL. The response carries code: EventNotFound.

application/json

{
  "status": {
    "acknowledged": "ok"
  }
}

GET /event/list — List events (paginated, with filters).

List events (paginated, with filters).

get

Returns events ordered by _id descending by default. The JSON response is an object {count, limit, offset, objects[]}.

Filters and pagination are query parameters. Pagination: offset, limit. Output: format (json (default) or csv); pretty (JSON only, default true). Filters are matched as IN lists (comma-separated): id (id list/ranges, e.g. 1,2-30,4), pollable (bool), type, basetype, objecttype, user_id, group_id, user_type, object_id, system_object_id. Time window: date_from, date_to (ISO timestamps, range on event.timestamp).

sort is a comma-separated list of field.DIR (DIR = ASC|DESC) over the fields _id, type, schema, object_id, system_object_id, object_version, timestamp, user_generated_displayname.

With format=csv the response is text/csv and these output options apply: csv_delimiter, csv_quote, csv_escape, csv_explode, csv_explode_array_concat, csv_max_length, cvs_use_bom.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

limitintegerOptional

Maximum number of events to return.

offsetintegerOptional

Number of events to skip.

formatstring · enumOptional

Response format. csv returns text/csv instead of JSON.

Default: jsonPossible values:

idstringOptional

Event id filter as a comma-separated list of ids and ranges, e.g. 1,2-30,4.

typestringOptional

Comma-separated list of event type values to match.

objecttypestringOptional

Comma-separated list of objecttype names to match.

user_idstringOptional

Comma-separated list of user ids to match.

date_fromstring · date-timeOptional

Lower bound (inclusive) on event.timestamp.

date_tostring · date-timeOptional

Upper bound on event.timestamp.

sortstringOptional

Comma-separated field.DIR ordering (DIR = ASC|DESC).

Responses

200

Object envelope of matching events (JSON format). With format=csv the response is text/csv instead.

application/jsontext/csv

countinteger · int64Required

Total number of events matching the filter (before limit/offset).

limitintegerOptional

Echo of the effective limit (0 = unlimited).

offsetintegerOptional

Echo of the requested offset.

400

A query filter could not be parsed (e.g. a malformed id range, an unknown sort field/direction, or an unknown format). The response carries code: ServerGeneric.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system right required for this operation: system.api.event[get] for reads (GET /event/{eventId}, GET /event/list) or system.api.event[delete] for deletes (DELETE /event/{eventId}, DELETE /event/list). system.root always suffices. There is no per-object ACL on events.

application/json

{
  "count": 1,
  "objects": [
    {
      "_basetype": "event",
      "event": {
        "type": "SEARCH"
      }
    }
  ]
}

POST /event/list — Bulk-write events.

Bulk-write events.

post

Writes the supplied array of events. Useful for batch tooling. As with POST /event, any authenticated user may write FRONTEND/PLUGIN event types; all other known event groups require system.root with skip_constraints=true, and a type unknown to the server is rejected with code: EventTypeNotAllowed. Unlike POST /event, this bulk operation is rejected with 400 ReadOnlyMode while the instance is in read-only mode.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

backgroundbooleanOptional

If true, the events are saved asynchronously: the request returns {"background": "ok"} immediately and per-event validation errors (e.g. a disallowed type) are not reported in the response.

skip_constraintsbooleanOptional

If true, all other known event groups (ADMIN, DOWNLOAD, EXPORT, INDEX, LOGIN_LOGOUT, SYSTEM, TASK, UPLOAD) may also be written — not just the FRONTEND/PLUGIN user types — and a top-level user object is accepted on each event. Requires system.root; a non-root caller that sets it receives a 400 ServerGeneric error.

Bodyobject · EventApi[]

application/json

An event record. fylr writes events for almost every server-side mutation (object insert/update, collection changes, ACL changes, email sends, login, ...).

_basetypestring · enumRequired

Fixed marker identifying this object as an event.

Possible values:

Responses

200

For a synchronous write the stored events are echoed as an array of EventApi. With background=true the body is {"background":"ok"}.

application/json

Response of POST /event/list. For a synchronous write this is the array of stored events (EventApi). With background=true the body is the acknowledgement object {"background": "ok"} and the events are saved asynchronously.

or

400

The request could not be processed. Possible code values: EventTypeNotAllowed (the payload's type is unknown, or is not a FRONTEND/PLUGIN user type and was not unlocked with root + skip_constraints), ServerGeneric (invalid JSON body, an unparseable query filter such as id/sort, a non-root caller passing skip_constraints, or an event carrying a user/user_id without skip_constraints), or ReadOnlyMode (the instance is in read-only mode; affects the write/delete operations only, not POST /event).

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

[
  {
    "_basetype": "event",
    "event": {
      "_id": 1,
      "type": "text",
      "object_id": 1,
      "object_version": 1,
      "global_object_id": "text",
      "system_object_id": 1,
      "schema": "text",
      "basetype": "text",
      "objecttype": "text",
      "timestamp": "2026-08-11T20:24:35.400Z",
      "pollable": true,
      "info": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "remote_addr": "text",
      "user_generated_displayname": "text"
    },
    "user": {
      "_basetype": "user",
      "_owner": true,
      "_pool_contact": true,
      "user": {
        "_id": 1,
        "lookup:_id": {
          "reference": "text"
        },
        "_generated_displayname": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "group": {
        "_id": 1,
        "lookup:_id": {
          "reference": "text"
        },
        "_generated_displayname": "text"
      }
    }
  }
]

DELETE /event/list — Bulk-delete events.

Bulk-delete events.

delete

Deletes every event matching the supplied filters. The filters are read from the query string — the same EventListQuery as GET /event/list (commonly id=..., plus type, date_from, date_to, user_id, ...); there is no request body. With no filters the match set is the entire event log, so deletion is unbounded. Requires the system.api.event[delete] system right (or system.root), and is rejected with 400 ReadOnlyMode while the instance is in read-only mode.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

idstringOptional

Event id filter as a comma-separated list of ids and ranges, e.g. 1,2-30,4. The matched events are deleted.

limitintegerOptional

Maximum number of matched events to delete.

typestringOptional

Comma-separated list of event type values to match.

date_fromstring · date-timeOptional

Lower bound (inclusive) on event.timestamp.

date_tostring · date-timeOptional

Upper bound on event.timestamp.

Responses

200

The matched events were deleted.

application/json

400

The request could not be processed. Possible code values: EventTypeNotAllowed (the payload's type is unknown, or is not a FRONTEND/PLUGIN user type and was not unlocked with root + skip_constraints), ServerGeneric (invalid JSON body, an unparseable query filter such as id/sort, a non-root caller passing skip_constraints, or an event carrying a user/user_id without skip_constraints), or ReadOnlyMode (the instance is in read-only mode; affects the write/delete operations only, not POST /event).

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system right required for this operation: system.api.event[get] for reads (GET /event/{eventId}, GET /event/list) or system.api.event[delete] for deletes (DELETE /event/{eventId}, DELETE /event/list). system.root always suffices. There is no per-object ACL on events.

application/json

{
  "status": {
    "acknowledged": "ok"
  }
}