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). Subject to global rate limiting; see the rate-limit section in the main reference.

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=1234567890123456789&category=workspace&subcategory=storage&limit=50" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "events": [
    {
      "event_id": "abc123xyz789def456ghi789jkl01",
      "created": "2025-01-20 10:30:45 UTC",
      "acknowledged": false,
      "event": "workspace_storage_file_added",
      "category": "workspace",
      "sub_category": "storage",
      "object_id": "def456ghi789jkl012mno345pqr67",
      "calling_user": "9876543210987654321",
      "calling_user_name": "Jane Smith",
      "org_id": "1111111111111111111",
      "workspace_id": "1234567890123456789",
      "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). Subject to global rate limiting; shares the events search rate limit bucket.

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=1234567890123456789&user_context=Focus%20on%20file%20uploads&limit=100" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "summary": {
    "text": "@[user:9876543210987654321:Jane Smith] uploaded 12 files...",
    "metrics": {
      "total_events": 50,
      "unique_actors": 5,
      "date_range": {
        "start": "2025-01-01 00:00:00 UTC",
        "end": "2025-01-20 10:30:45 UTC"
      },
      "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/abc123xyz789def456ghi789jkl01/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "event": {
    "event_id": "abc123xyz789def456ghi789jkl01",
    "created": "2025-01-20 10:30:45 UTC",
    "acknowledged": false,
    "event": "workspace_storage_file_added",
    "category": "workspace",
    "sub_category": "storage",
    "object_id": "def456ghi789jkl012mno345pqr67",
    "calling_user": "9876543210987654321",
    "calling_user_name": "Jane Smith",
    "org_id": "1111111111111111111",
    "workspace_id": "1234567890123456789",
    "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/abc123xyz789def456ghi789jkl01/ack/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true
}

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

File Share Lifecycle

Durable single-file File Share events. Category share, external visibility, member permission. Anchored to the owning workspace; the affected File Share id travels in the event data as file_share_id.

• file_share_created — A durable File Share was created
• file_share_updated — A File Share's settings (title / access tier / password) were updated
• file_share_content_updated — The shared file's content was replaced (external edit / write-back)
• file_share_deleted — A File Share was deleted
• file_share_access_granted — A per-user grant (view / download / edit) was added or raised
• file_share_access_revoked — A per-user grant was revoked

AI

• ai_chat_created / ai_chat_updated / ai_chat_deleted — AI agent conversation lifecycle
• ai_chat_new_message — New message in an AI agent conversation
• ai_chat_published — AI agent conversation published (chat publish is currently disabled platform-wide — capabilities.can_publish_agent_chat is false; fires only for chats published before the disable)
• 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 (deprecated — see File Share Lifecycle)

QuickShare creation is deprecated in favor of the durable File Share; these events fire only for the draining QuickShare population. New single-file sharing emits the file_share_* events above.

• 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

Billing

• subscription_created — fires when a new subscription is initiated
• subscription_cancel_scheduled — fires when a customer schedules cancellation; the subscription remains active until cancel_at
• subscription_cancelled — fires when the subscription is actually terminated by the payment provider (at cancel_at)
• 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
• task_moved — fires when a task is moved between lists
• tasks_reordered — fires when tasks are reordered within a list
• task_lists_reordered — fires when task lists are reordered

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=abc123xyz789def456ghi789jkl01&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). Subject to global rate limiting; see the rate-limit section in the main reference. 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": true,
  "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": true,
  "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/1234567890123456789/?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/1234567890123456789" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "expires_in": 86400,
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Fields

Access Requirements

Token Lifetime

The default expires_in for User, Organization, Workspace, and File Share tokens is 86400 (24 hours). Share and Workflow tokens are shorter-lived — always inspect the expires_in field on the response and refresh the token before it expires. Both channels use a short TTL because the recipient's standing can change during a session, and the token freezes that standing at mint time: a workflow's OBSERVE standing can change (a grant is revoked, the workflow's visibility tightens, or the caller is removed from the parent workspace), and a share guest can be removed or have their access level downgraded. The short TTL bounds how long an open connection can keep delivering events under a now-stale authorization; on reconnect the freshly minted token reflects the current standing. See the Workflow Orchestration reference for the workflow-specific realtime contract.

Error Responses

WebSocket Connection

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

Where {auth_token} is the JWT returned from the auth endpoint above — it is the entire query string (no token= key, no other query parameters).

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": "abc123def456ghi789jkl012mno34",
  "calling_user": "1234567890123456789",
  "activity_field": "storage",
  "data": {
    "name": "report.pdf",
    "parent_node_id": "xyz789...",
    "size": 1048576
  }
}

event Message Fields

Backwards Compatibility

activity messages are sent for every change a recipient is permitted to observe. 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.

Per-recipient scoping (share channels): On a share channel, each outgoing activity/event frame is scoped to the receiving guest's share access before it is delivered. A guest receives only the changes their access level permits them to observe — frames they may not see are suppressed, and content detail (file names, node identifiers, enriched data) is collapsed to a bare category or dropped for guests with restricted file visibility. Members and all non-share channels (user / organization / workspace / workflow) are unaffected and receive the full frame. Do not assume a share guest will observe every change on the channel, or that a delivered activity frame will always carry an enriched event companion.

Workflow Channel — invalidation-nudge only

Workflow profiles use the same wss:// endpoint and frame shape, but the workflow runtime events are administrator-level, so the workflow channel ONLY emits activity messages — never enriched event messages. The frame's activity array carries identifiers like details (workflow lifecycle changed) or steps:{step_occurrence_id} (a step occurrence transitioned); the client refetches GET /workflows/{workflow_id}/state/ (or the targeted step endpoint) as authoritative state. WebSocket delivery on the workflow channel is best-effort and not durable — for a transactional, gap-free record of workflow state changes use the audit-event log (GET /workflows/{workflow_id}/audit/events/). The full contract — connection flow, the activity-field set, reconnect behavior, mid-session authorization changes — lives in the Workflow Orchestration reference.

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.

Workflow profiles do not currently support the activity-poll fallback. The /current/activity/poll/{profile_id}/ endpoint only services User / Organization / Workspace / Share / File Share profiles. For workflow channels, on reconnect refetch GET /workflows/{workflow_id}/state/ (and any scoped step / obligation endpoint the UI was tracking) — that surface is authoritative and is what the realtime channel's nudges tell the client to re-read. For a transactional, gap-free record of workflow state changes, use the audit-event log (GET /workflows/{workflow_id}/audit/events/).

Realtime Auth (Collaborative Rooms)

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

Generate Realtime Token

Auth: Required (JWT). Subject to global rate limiting; see the rate-limit section in the main reference. No credit consumption.

Path Parameters

Example Request

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

Response (200 OK)

{
  "result": true,
  "expires_in": 86400,
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Access Requirements

Error Responses

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

Generate Realtime Note Token

Auth: Required (JWT). Subject to global rate limiting; see the rate-limit section in the main reference. No credit consumption.

Path Parameters

Example Request

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

Response (200 OK)

{
  "result": true,
  "expires_in": 900,
  "auth_token": "{realtime_note_token}"
}

Response Fields

Access Requirements

The token's granted capabilities are frozen at mint time from your current permission on the workspace:

Because the capabilities are frozen for the token's lifetime, a permission change made after a token is issued takes effect on the next token refresh (at most ~15 minutes later).

Error Responses

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": true,
  "room_id": "1234567890123456789"
}

Response Fields

Error Responses

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

Validate Realtime Note Token

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

Example Request

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

Response (200 OK)

{
  "result": true,
  "profile": "1234567890123456789",
  "node": "n5mno-pqrst-uvwxy-z1234-abcde-fghi",
  "perm": "edit"
}

Response Fields

Error Responses

Notes: Only validates tokens with the realtime-note scope; any other token is rejected. Validation is performed using the token alone — signature, expiry, scope, audience, and the perm/capability binding are all checked.