Events & Activity Event search, activity polling, WebSocket realtime.

Events capture every action in the system — file operations, membership changes, comments, AI activity, billing, workflow, and more. Use the event search endpoints to query the log, activity polling for efficient change detection, and WebSocket for real-time delivery.

Events Search

Search and filter the event log. Events capture every action in the system — file operations, membership changes, comments, AI activity, billing, workflow, and more.

Search Events

Auth: Required (JWT). Rate limited: 5 per 3s, 15 per 30s, 120 per 10min.

Query Parameters

Profile filter priority: If multiple profile filters are supplied, priority is: user_id > org_id > workspace_id > share_id. Only the highest-priority filter is applied.

Example Request

curl -X GET "https://api.fast.io/current/events/search/?workspace_id=12345678901234567890&category=workspace&subcategory=storage&limit=50" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "response": {
    "events": [
      {
        "event_id": "evt_abc123xyz789",
        "created": "2025-01-20 10:30:45",
        "acknowledged": false,
        "event": "workspace_storage_file_added",
        "category": "workspace",
        "sub_category": "storage",
        "object_id": "node_def456ghi789",
        "calling_user": "98765432109876543210",
        "calling_user_name": "Jane Smith",
        "org_id": "11111111111111111111",
        "workspace_id": "12345678901234567890",
        "filename": "quarterly_report.pdf",
        "file_size": 2485760
      }
    ]
  }
}

Response Fields

Additional event-specific fields (e.g., filename, file_size, member_name) vary by event type.

Error Responses

Notes: Results may be slightly delayed due to caching. OAuth scoped tokens enforce entity-level access: events are filtered to only entities within the token's scope. Events the user cannot access are automatically excluded from results.

Summarize Events (AI)

Auth: Required (JWT). Shares the search rate limit.

Additional Query Parameters

All other parameters are identical to Search Events.

Example Request

curl -X GET "https://api.fast.io/current/events/search/summarize/?workspace_id=12345678901234567890&user_context=Focus%20on%20file%20uploads&limit=100" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "response": {
    "summary": {
      "text": "@[user:98765432109876543210:Jane Smith] uploaded 12 files...",
      "metrics": {
        "total_events": 50,
        "unique_actors": 5,
        "date_range": {
          "start": "2025-01-01T00:00:00+00:00",
          "end": "2025-01-20T10:30:45+00:00"
        },
        "categories": {
          "storage": 30,
          "members": 20
        }
      }
    },
    "events": [ ... ]
  }
}

Response Fields (additional to events search)

Summary Mention Pill Formats

Notes: Summary generation failures are non-fatal: summary is null but events are still returned. Requires a billable organization for AI token billing (resolved from profile context).

Event Details

Auth: Required (JWT). Default rate limiting. No credit consumption.

Path Parameters

Example Request

curl -X GET "https://api.fast.io/current/event/evt_abc123xyz789/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "response": {
    "event": {
      "event_id": "evt_abc123xyz789",
      "created": "2025-01-20 10:30:45",
      "acknowledged": false,
      "event": "workspace_storage_file_added",
      "category": "workspace",
      "sub_category": "storage",
      "object_id": "node_def456ghi789",
      "calling_user": "98765432109876543210",
      "calling_user_name": "Jane Smith",
      "org_id": "11111111111111111111",
      "workspace_id": "12345678901234567890",
      "filename": "quarterly_report.pdf",
      "file_size": 2485760
    }
  }
}

Access Rules

Error Responses

Acknowledge Event

Auth: Required (JWT). Default rate limiting.

Path Parameters

Example Request

curl -X POST "https://api.fast.io/current/event/evt_abc123xyz789/ack/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes"
}

Error Responses

Note: Acknowledgment is per-user. Acknowledging for one user does not affect others. Same access rules as event details apply.

Compact Responses (output=)

Every endpoint that returns event objects (search, details) accepts an optional output query parameter that selects the response shape. A single detail-level token may be combined with modifier tokens; specifying two detail levels (e.g. ?output=terse,standard) returns HTTP 400. When output= is omitted, responses are full and byte-for-byte unchanged.

Use terse for activity feed tickers and unread-count polling — it carries the event identity (event_id), name (event), category, target object, and a timestamp (created), which is the minimum a feed row needs to render without a follow-up fetch. Use standard for the most common event list/detail views — it adds subcategory, every profile-link id (calling user, owning org/workspace/share), the acknowledgment flag, the template object (which carries the human-readable description and any template params), and the render-hint enums: severity (drives feed-row color/icon), visibility (distinguishes the Activity, Audit-Log, and internal tabs), and notification (drives bell/notification rendering). Use full (or omit the parameter) for audit-log exports and event schema introspection. Unknown tokens are silently ignored. Add the markdown modifier (e.g. ?output=standard,markdown) to receive the response as GitHub-flavored Markdown (Content-Type: text/markdown; charset=UTF-8) instead of JSON — see the cross-cutting ?output= reference for the full contract.

Event Categories

Event Subcategories

Event Visibility Levels

Default (no visibility parameter): returns both external_audit_log and external events, excludes internal.

Event Permission Levels

When querying with visibility=external_audit_log, targeted permission checks are bypassed.

Event Names Reference

Workspace Storage

• workspace_storage_file_added — File uploaded
• workspace_storage_file_deleted — File trashed
• workspace_storage_file_moved — File moved
• workspace_storage_file_copied — File copied
• workspace_storage_file_updated — File metadata updated
• workspace_storage_file_restored — File restored from trash
• workspace_storage_file_version_restored — File version restored
• workspace_storage_folder_created — Folder created
• workspace_storage_folder_deleted — Folder trashed
• workspace_storage_folder_moved — Folder moved
• workspace_storage_download_token_created — Download token issued
• workspace_storage_zip_downloaded — ZIP download completed
• workspace_storage_link_added — Link added

Share Storage

• share_storage_file_added — File uploaded
• share_storage_file_deleted — File trashed
• share_storage_file_moved — File moved
• share_storage_file_copied — File copied
• share_storage_file_updated — File metadata updated
• share_storage_file_restored — File restored
• share_storage_folder_created — Folder created
• share_storage_folder_deleted — Folder trashed
• share_storage_folder_moved — Folder moved
• share_storage_download_token_created — Download token issued
• share_storage_zip_downloaded — ZIP download completed

Comments

• comment_created — Comment created
• comment_updated — Comment updated
• comment_deleted — Comment deleted
• comment_mentioned — User mentioned in comment (targeted permission)
• comment_replied — Reply to a comment
• comment_reaction — Reaction added

Membership

• added_member_to_org / removed_member_from_org — Org membership
• added_member_to_workspace / removed_member_from_workspace — Workspace membership
• added_member_to_share / removed_member_from_share — Share membership
• membership_updated — Permission changes

Workspace Lifecycle

• workspace_created / workspace_updated / workspace_deleted
• workspace_archived / workspace_unarchived

Share Lifecycle

• share_created / share_updated / share_deleted
• share_archived / share_unarchived
• share_imported_to_workspace — Share imported into workspace

AI

• ai_chat_created / ai_chat_updated / ai_chat_deleted — Chat lifecycle
• ai_chat_new_message — New AI chat message
• ai_chat_published — Chat published
• node_ai_summary_created — AI summary generated for a file
• workspace_ai_share_created — AI share created in workspace

Metadata

• metadata_kv_update / metadata_kv_delete / metadata_kv_extract
• metadata_template_update / metadata_template_delete / metadata_template_select
• metadata_view_update / metadata_view_delete

Quick Shares

• workspace_quickshare_created / workspace_quickshare_updated / workspace_quickshare_deleted
• workspace_quickshare_file_downloaded / workspace_quickshare_file_previewed

Invitations

• invitation_email_sent / invitation_accepted / invitation_declined

User

• user_created / user_updated / user_deleted
• user_email_reset / user_asset_updated

Organization

• org_created / org_updated / org_closed
• org_transfer_token_created / org_transfer_completed

Billing

• subscription_created / subscription_cancelled
• billing_free_trial_ended

Workflow

• task_list_created / task_list_updated / task_list_deleted
• task_created / task_updated / task_deleted
• task_status_changed / task_assigned / task_completed
• worklog_entry_created
• worklog_interjection_created / worklog_interjection_acknowledged
• approval_requested / approval_approved / approval_rejected
• todo_created / todo_toggled / todo_deleted / todo_updated

Event Search Examples

Recent comments in a workspace

GET /current/events/search/?workspace_id={id}&subcategory=comments

File uploads to a share in a date range

GET /current/events/search/?share_id={id}&event=share_storage_file_added&created-min=2025-12-01T06:00:00Z

Membership changes in an org

GET /current/events/search/?org_id={id}&subcategory=members

AI activity in a workspace

GET /current/events/search/?workspace_id={id}&category=ai

Unacknowledged events for a user

GET /current/events/search/?user_id={id}&acknowledged=false

Audit log events only

GET /current/events/search/?workspace_id={id}&visibility=external_audit_log&limit=100

Child events of a batch operation

GET /current/events/search/?parent_event_id=evt_abc123xyz789&limit=100

Workflow activity in a workspace

GET /current/events/search/?workspace_id={id}&category=workflow

Activity Polling

Long-poll endpoints for efficient change detection. The server holds the connection open and returns immediately when something changes, avoiding expensive resource polling.

Poll User Activity

Auth: Required (JWT). Rate limited: 200 per 60s, 1000 per hour. No credit consumption.

Query Parameters

Example Request

curl -X GET "https://api.fast.io/current/activity/poll/?wait=30&lastactivity=2025-01-20%2010:30:45.123456" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK — activity found)

{
  "result": "yes",
  "response": {
    "results": 3,
    "activity": {
      "storage": "2025-01-20 10:30:45.123456 UTC",
      "members": "2025-01-20 09:15:22.654321 UTC",
      "settings": "2025-01-19 14:00:00.000000 UTC"
    },
    "lastactivity": "2025-01-20 10:30:45.123456 UTC"
  }
}

Response (200 OK — no activity)

{
  "result": "yes",
  "response": {
    "results": 0,
    "activity": []
  }
}

Response Fields

Error Responses

Poll Profile Activity

Auth: Required (JWT). Same rate limits and parameters as Poll User Activity.

Path Parameters

Access Requirements

Example Request

curl -X GET "https://api.fast.io/current/activity/poll/12345678901234567890/?wait=30&fields=storage,members&updated=1&lastactivity=2025-01-20%2010:30:45.123456" \
  -H "Authorization: Bearer {jwt_token}"

Response format is identical to Poll User Activity.

Polling Workflow

1. Make initial poll request (no lastactivity parameter)
2. Receive response with activity fields and lastactivity timestamp
3. Process changes by fetching updated resources based on activity field names
4. Make next poll with lastactivity from previous response
5. Repeat — server returns immediately on change, or after wait seconds timeout

Activity Key Patterns

Anti-Patterns

• Do NOT loop on resource detail endpoints to wait for previews or processing.
• Instead, poll on the workspace/share and watch for the relevant activity key.
• For uploads, use your user ID as the profile_id since upload progress is tied to the user, not a workspace.

WebSocket (Real-Time)

Optional real-time delivery (~300ms latency vs ~1s for polling). Sends both activity messages (field names for change detection) and enriched event messages (full event details) via WebSocket. Backwards compatible — existing clients continue to work without changes.

WebSocket Auth

Auth: Required (JWT). No credit consumption.

Path Parameters

Example Request

curl -X GET "https://api.fast.io/current/websocket/auth/12345678901234567890" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "response": {
    "expires_in": 86400,
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "current_api_version": "1.0"
}

Response Fields

Access Requirements

Error Responses

WebSocket Connection

Connect to: wss://{host}/api/websocket/?token={auth_token}

Where {auth_token} is the JWT returned from the auth endpoint above.

Message Types

The server pushes two types of JSON messages:

activity Messages

Indicate which resource categories changed. Use these to know what to re-fetch:

{
  "response": "activity",
  "activity": ["storage:2abc...", "preview:2abc..."]
}

The activity array contains the same activity key patterns as the polling endpoint.

event Messages

Sent alongside activity messages when structured event data is available. Provide full event details for immediate UI updates without a follow-up API call:

{
  "result": true,
  "response": "event",
  "time": "2026-03-22 14:30:45.123456 UTC",
  "timestamp": "1711123456.1234",
  "event": "workspace_storage_file_added",
  "category": "workspace",
  "sub_category": "storage",
  "object_id": "abc123def456ghi789jkl012mno345",
  "calling_user": "12345678901234567890",
  "activity_field": "storage",
  "data": {
    "name": "report.pdf",
    "parent_node_id": "xyz789...",
    "size": 1048576
  }
}

event Message Fields

Backwards Compatibility

activity messages are always sent. event messages are supplementary — sent alongside activity messages when structured event data is available. Existing clients need no changes. Event payloads are kept under ~4KB.

Permission gating: Enriched event messages are only sent for member-level events. Admin and targeted events receive only the activity message.

Fallback

If the WebSocket connection drops, fall back to long-polling (GET /current/activity/poll/{profile_id}/). Activity polling returns field names and timestamps. To retrieve full event details after reconnection, use GET /current/events/search/ with a created-min filter.

Realtime Auth (Collaborative Rooms)

Separate from WebSocket activity channels, these endpoints provide authentication for collaborative editing rooms.

Generate Realtime Token

Auth: Required (JWT). Not rate limited. No credit consumption.

Path Parameters

Example Request

curl -X GET "https://api.fast.io/current/realtime/auth/12345678901234567890" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "response": {
    "expires_in": 86400,
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "current_api_version": "1.0"
}

Access Requirements

Error Responses

Note: Only workspace and share profile types are accepted as room IDs.

Validate Realtime Token

Auth: Bearer token in Authorization header (the realtime JWT to validate, not a user JWT).

Example Request

curl -X GET "https://api.fast.io/current/realtime/auth/validate/" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
  "result": "yes",
  "response": {
    "room_id": "12345678901234567890"
  },
  "current_api_version": "1.0"
}

Response Fields

Error Responses

Notes: Only validates tokens with realtime scope. WebSocket-scoped tokens are rejected. Validation is performed using the JWT alone.