post__systemevent

POST /systemevent

Query System Events

Query system events from the SystemEvent table with advanced filtering and pagination capabilities. This endpoint allows users to retrieve audit logs and system activity events based on various criteria including timestamps, context, event types, users, and workspaces.

Key Features:

• Advanced filtering by timestamp range, context, event type, user, and workspace

• Role-based access control (OWNER/ADMIN can query any user's events, regular users limited to their own)

• Pagination support with configurable skip and take parameters

• Default 24-hour time window when no timestamps are specified

• Context and event type translation from numeric indices to human-readable strings

• Read/unread tracking: Optional filter to return only unread events; each event includes a showUnread flag for the current user

• Comprehensive audit logging for security and compliance

Authentication:

• Requires valid Bearer token authentication

• User must be associated with an organization

• Role-based permissions determine data access scope

Access Control:

• OWNER/ADMINISTRATORS: Can query events for any user and workspace within their organization

• Regular Users: Limited to querying their own events and workspaces they belong to

• All users can only access events from their own organization

Filtering Options:

• Timestamp Range: Filter events by from_timestamp and to_timestamp (ISO 8601 format)

• Context: Filter by context type (workspace, bucket, repo, user, org, etc.)

• Event Type: Filter by event type (created, updated, deleted)

• User: Filter by specific user ID (role-dependent)

• Workspace: Filter by specific workspace ID (role-dependent)

• Context ID: Filter by specific context identifier

• Show unread only: When showUnread is true, only events that the current user has not read are returned (useful for notification badges and “unread” views)

Pagination:

• skip: Number of records to skip (default: 0, minimum: 0)

• take: Number of records to return (default: 20, minimum: 1, maximum: 100)

Context Types:

• workspace (0)

• bucket (1)

• repo (2)

• user (3)

• org (4)

• workspaceuser (5)

• apikey (6)

• usersettings (7)

• orgsettings (8)

• flashbacknode (9)

• orgkey (10)

Event Types:

• created (0)

• updated (1)

• deleted (2)

Read/Unread behavior

• Request (showUnread): Optional boolean. When true, the API returns only events that the current authenticated user has not marked as read. When omitted or false, all events matching the other filters are returned (each event still includes a showUnread value).

• Response (showUnread on each event): Every event in the response includes a showUnread boolean indicating whether the current user has read that event. true means the user has not read it (e.g. for highlighting in a notification list); false means they have. Read state is stored per user and per event on the server.

• To mark an event as read or unread, use POST /systemevent/:id/read and DELETE /systemevent/:id/read.

TypeScript Client Library

public getSystemEvents = async (data: SystemEventQueryRequest): Promise<SystemEventQueryResponse> => {
  return this.makeRequest<SystemEventQueryResponse>('systemevent', 'POST', data);
};

Code Samples

Shell

# Query system events for the last 24 hours
curl -X POST https://backend.flashback.tech/systemevent \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your-jwt-token' \
  -d '{
    "skip": 0,
    "take": 20
  }'

# Query events for a specific time range and context
curl -X POST https://backend.flashback.tech/systemevent \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your-jwt-token' \
  -d '{
    "from_timestamp": "2024-01-01T00:00:00.000Z",
    "to_timestamp": "2024-01-31T23:59:59.999Z",
    "context": 0,
    "event": 0,
    "skip": 0,
    "take": 50
  }'

HTTP

JavaScript

Ruby

Python

PHP

Java

Go

Body parameter

{
  "from_timestamp": "2024-01-01T00:00:00.000Z",
  "to_timestamp": "2024-01-31T23:59:59.999Z",
  "contextId": "workspace-123",
  "context": 0,
  "event": 0,
  "userId": "user-456",
  "workspaceId": "workspace-789",
  "showUnread": false,
  "skip": 0,
  "take": 20
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	System event query parameters
» from_timestamp	body	string	false	Start timestamp for filtering events (ISO 8601 format)
» to_timestamp	body	string	false	End timestamp for filtering events (ISO 8601 format)
» contextId	body	string	false	Specific context identifier to filter by
» context	body	number	false	Context type index (0-10)
» event	body	number	false	Event type index (0-2)
» userId	body	string	false	User ID to filter by (role-dependent access)
» workspaceId	body	string	false	Workspace ID to filter by (role-dependent access)
» showUnread	body	boolean	false	When true, only return events the current user has not read
» skip	body	number	true	Number of records to skip (minimum: 0)
» take	body	number	true	Number of records to return (minimum: 1, maximum: 100)

Context Type Values

Index	Context Type	Description
0	workspace	Workspace-related events
1	bucket	Bucket-related events
2	repo	Repository-related events
3	user	User-related events
4	org	Organization-related events
5	workspaceuser	Workspace user events
6	apikey	API key events
7	usersettings	User settings events
8	orgsettings	Organization settings events
9	flashbacknode	Flashback node events
10	orgkey	Organization key events

Event Type Values

Index	Event Type	Description
0	created	Resource created
1	updated	Resource updated
2	deleted	Resource deleted

Example responses

200 Response

{
  "events": [
    {
      "id": 12345,
      "timestamp": "2024-01-15T10:30:00.000Z",
      "contextId": "workspace-123",
      "context": "workspace",
      "event": "created",
      "orgId": "org-456",
      "userId": "user-789",
      "userName": "Jane Doe",
      "userEmail": "[email protected]",
      "workspaceId": "workspace-123",
      "jsonData": "{\"name\":\"My Workspace\",\"description\":\"A new workspace\"}",
      "showUnread": true
    },
    {
      "id": 12344,
      "timestamp": "2024-01-15T10:25:00.000Z",
      "contextId": "bucket-456",
      "context": "bucket",
      "event": "updated",
      "orgId": "org-456",
      "userId": "user-789",
      "userName": "Jane Doe",
      "userEmail": "[email protected]",
      "workspaceId": "workspace-123",
      "jsonData": "{\"name\":\"Updated Bucket\",\"region\":\"us-east-1\"}",
      "showUnread": false
    }
  ],
  "total": 150,
  "skip": 0,
  "take": 20
}

400 Response

{
  "error": "skip must be >= 0"
}

401 Response

{
  "error": "Unauthorized"
}

403 Response

{
  "error": "Insufficient permissions to query other users' events"
}

500 Response

{
  "error": "Internal server error"
}

Responses

Status	Meaning	Description	Schema
200	OK	System events retrieved successfully	Inline
400	Bad Request	Validation error or invalid parameters	Inline
401	Unauthorized	Authentication required or user not found	Inline
403	Forbidden	Insufficient permissions for requested data	Inline
500	Internal Server Error	Internal server error	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» events	array	true	none	Array of system events
»» id	number	true	none	Unique event identifier
»» timestamp	string	true	none	Event timestamp in ISO 8601 format
»» contextId	string	true	none	Context identifier
»» context	string	true	none	Human-readable context type
»» event	string	true	none	Human-readable event type
»» orgId	string	true	none	Organization ID
»» userId	string	true	none	User ID who triggered the event
»» userName	string	true	none	Display name of the user who triggered the event
»» userEmail	string	true	none	Email of the user who triggered the event
»» workspaceId	string	false	none	Workspace ID (null if not applicable)
»» jsonData	string	false	none	Additional event data in JSON format
»» showUnread	boolean	true	none	Whether the current user has not read this event; true = unread, false = read
» total	number	true	none	Total number of events matching the query
» skip	number	true	none	Number of records skipped
» take	number	true	none	Number of records returned

Status Code 400

Name	Type	Required	Restrictions	Description
» error	string	true	none	Error message describing the validation issue

Status Code 401

Name	Type	Required	Restrictions	Description
» error	string	true	none	Error message indicating authentication failure

Status Code 403

Name	Type	Required	Restrictions	Description
» error	string	true	none	Error message indicating insufficient permissions

Status Code 500

Name	Type	Required	Restrictions	Description
» error	string	true	none	Error message describing the internal error

This operation requires authentication via Bearer token and enforces role-based access control for data security.