API Reference

Base URL: https://api.fluidsoul.dev (or your self-hosted instance)

Authentication

All endpoints except /health require two headers:

Authorization: Bearer <api-token>
X-Workspace-Id: <workspace-uuid>

Optional: X-Request-Id: <uuid> for request tracing.

Endpoints

GET /health

Liveness check. No authentication required.

Response: { "status": "ok" }

POST /v1/events/ingest

Record a user action event.

Body:

{
  "user_id": "user_123",
  "event_type": "report_viewed",
  "event_time": "2025-01-15T10:30:00Z",
  "metadata": { "category": "analytics" }
}

Response: 201 Created

POST /v1/context/refresh

Recompute the user's context profile from all their events.

Body:

{ "user_id": "user_123" }

Response: The full UserContext object.

GET /v1/context/users/:userId

Read the current context for a user.

Response: The full UserContext object, or 404 if no context exists.

GET /v1/workspace/config

Read the workspace's rules config.

Response: The RulesConfig object. See Configuring Rules.

PUT /v1/workspace/config

Update the workspace's rules config. Replaces the entire config. The server validates the JSON before saving.

Body: A valid RulesConfig JSON object.

Response: { "status": "ok" }

POST /v1/privacy/export

Export all data for a user (GDPR).

Body: { "user_id": "user_123" }

Response: All events, context, and audit entries for the user.

DELETE /v1/privacy/delete

Delete all data for a user (GDPR).

Body: { "user_id": "user_123" }

Response: Counts of deleted records.

GET /v1/audit/logs

Query audit logs. Supports pagination.

Query params: limit (default 50), offset (default 0)

Response: Array of audit entries.

UserContext shape

{
  "id": "uuid",
  "workspace_id": "uuid",
  "user_id": "user_123",
  "user_category": "analyst",
  "preferred_mode": "analyst",
  "feature_priorities": ["reports", "analytics", "data_export"],
  "recommended_defaults": {
    "default_view": "reports",
    "default_period": "weekly"
  },
  "engagement_level": "high",
  "user_maturity": "intermediate",
  "confidence_scores": {
    "user_category": 0.85,
    "preferred_mode": 0.72,
    "engagement_level": 0.9,
    "user_maturity": 0.7
  },
  "explainability": [
    "Classified as 'analyst' based on 12 analyst and 3 executive signals out of 47 total events."
  ],
  "user_narrative": "This is an engaged analyst who primarily...",
  "inference_source": "rules+llm",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T12:30:00Z"
}

Error responses

All errors return: { "error": "description" }