Retrieve an event

GET /api/v1/event/<id>?token=<token>

Retrieves an event from the database.

Path parameters


`id`	Event ID (integer)

Query String


`token`	Session token acquired with /api/v1/session

Output

An event.

Permissions

The user must be authenticated and requires the system.api.event.get system right.

HTTP status codes


200	Success
400	API error: something is malformed
400	Event Not Found: event `id` not found
500	Server error: internal server error

Poll events

GET /api/v1/event/poll[/<last_max_id>]?token=<token>[&limit=<limit>]

Events can be polled, so that a frontend can refresh information regularly.

Path parameters


`last_max_id`	Event ID last seen (integer): This must be at least `session.current_max_event_id`. Defaults to `session.current_max_event_idr` if unset.

Query String


`token`	Session token acquired with /api/v1/session
`limit`	The maximum number of returned events (integer, optional). `25` if unset. `1000` if set to `0`. Internal maximum: `1000`.

Output

Returns all new Events with an ID greater than last_max_id. At least 1 and at most 1000 events are returned in the response. The Event’s output format is the Short format of type Event.

Events may be filtered on a per user basis. Currently this call will return no events for an unauthenticated session.

Permissions

The user must be authenticated.

Exceptions:

OBJECT_INSERT events are only returned if they were generated within the requesting session
OBJECT_UPDATE events for type user are only returned if they where generated by the requesting user
Not all events are generally pollable. Events need to be stored with pollableset to true.

HTTP status codes


200	Success
400	API error: something is malformed
500	Server error: internal server error

List events

GET /api/v1/event/list?token=<token>&...

Query String


`token`	Session token acquired with /api/v1/session
`limit`	The maximum number of returned events (integer, optional). `1000` if unset. Internal maximum: `1000`.
`offset`	The number of entries skipped in result set (integer, optional). `0` if unset.
`pollable`	Filter for `pollable` attribute (boolean, optional). No filter if unset.
`type`	Filter for `type` attribute (comma separated string list, optional). No filter if unset.
`base_type`	Filter for `base_type` attribute (comma separated string list, optional). No filter if unset.
`user_id`	Filter for `user_id` attribute: one or more IDs of users (comma separated integer list, optional). No filter if unset.
`group_id`	Filter for `group_id` attribute: one or more IDs of groups (comma separated integer list, optional). No filter if unset.
`user_type`	Filter for `user_type` attribute (comma separated string list, optional). No filter if unset.
`date_from`	Filter for minimum creation date/time (datetime, optional). No filter if unset.
`date_to`	Filter for maximum creation date/time (datetime, optional). No filter if unset.
`sort`	List of sort definitions (comma-separated). Per definition the field name is mandatory, the direction (`ASC` or `DESC`) is optional (defaulting to `ASC`). Supported fields are `_id`, `type`, `object_version`, `schema`, `object_id`, `timestamp`, `user_generated_displayname`. Example: `sort=schema,type.ASC,base_type.ASC,_id.DESC`. Default is `_id.DESC`.
`format`	Output format (string, optional). `json` and `csv` formats are supported. `json` is used if unset.
`csv_delimiter`	CSV field delimiter (string, optional). Only for `format=csv`, `,` if unset. If a horizontal tab character should be used, it’s URL-encoded ASCII value has to be specified: `%09`.
`csv_quote`	CSV quote character (string, optional). Only for `format=csv`, `"` if unset.
`csv_escape`	CSV escape character (string, optional). Only for `format=csv`, `"` if unset.
`csv_use_bom`	Add UTF-8 byte order mark (boolean, optional). Only for `format=csv`, `false` if unset.
`csv_explode`	Event info is written per key into individual columns (boolean, optional). Only for `format=csv`, `false` if unset. Column names are prefixed using `info.`
`csv_explode_array_concat`	Array values in event info are written as a string separated by the value of this parameter. (string, optional). Only for `format=csv&csv_explode=true`.
`csv_max_length`	Trim CSV column entries that contain more tokens than this value (integer, optional). If the value is `0`, the complete column content is exported. Only for `format=csv`, `100` if unset.
`skip_count`	Skip output of total `count` to speed up request (boolean, optional). Defaults to `false`. Available in version 5.139+.

Remarks:

user_id, group_id and user_type expand the list of users of the events:
- all users with any of the IDs from user_id are included
- all users from any of the groups with IDs from group_id are included
- all users with any of the types from user_type are included

Output

Returns all events matching the given filters. The event’s output format is the short format of type Event.

Permissions

The user must be authenticated and requires the system.api.event.get system right.

HTTP status codes


200	Success
400	API error: something is malformed
500	Server error: internal server error

Insert a new event

POST /api/v1/event?token=<token>

The client can insert events of the types SEARCH and DETAIL_VIEW. The event can only be POSTed if the corresponding base configuration (system.log.search or system.log.detail_view) is enabled. Otherwise, this call returns an error.

Query String


`token`	Session token acquired with /api/v1/session

Input

The input is a JSON object containing:

Attribute	Description
`type`	The event type (string): one of`SEARCH`, `DETAIL_VIEW`
`info`	The event information (object, optional): defaults to `{}`
`object_version`	The event object version
`object_id`	The event object ID
`objecttype`	The object type name.

Output

The newly created Event.

Permissions

The user must be authenticated.

HTTP status codes


200	Success
400	API error: something is malformed
400	Not Authenticated: session is not authenticated
400	Event Type Disabled: event type is disabled
500	Server error: internal server error

Delete events

DELETE /api/v1/event?token=<token>&...

Query String


`token`	Session token acquired with /api/v1/session
`limit`	The maximum number of deleted events.
`offset`	The number of entries skipped in result set.
`pollable`	Filter for `pollable` attribute.
`type`	Filter for `type` attribute.
`base_type`	Filter for `base_type` attribute.
`user_id`	Filter for `user_id` attribute.
`group_id`	Filter for `group_id` attribute.
`user_type`	Filter for `user_type` attribute.
`date_from`	Filter for minimum creation date/time.
`date_to`	Filter for maximum creation date/time.

All filter parameters from GET /api/v1/event/list are supported and used in the same way. All limits and default values for parameters also apply here.

As an alternative to supplying filters it is also possible to send a list of event IDs to delete. This is done by using a JSON list in the request body. Example:

[
  2,
  42,
  73
]

When using this option only the token query parameter is valid.

Output

Returns an JSON object containing the number of deleted events as count.

Permissions

The user must be authenticated and requires the system.api.event.delete system right.

HTTP status codes


200	Success
400	API error: something is malformed
500	Server error: internal server error