Trichspace Docs

Welcome to Trichspace

Trichspace is a real-time behavioral intelligence engine that helps platforms understand, process, and react to user behavior instantly.

Instead of collecting events and processing them later, Trichspace evaluates every event as it happens.

Getting Started

What You Need Before Starting

• A verified account

• A project

• An API key

• At least one rule

• Your application connected to the API

Once completed, your system can begin streaming live events into the Trichspace engine.

1. Create an Account

Visit the Trichspace signup page and create an account using your email and password.

Required Fields

• Email address

• Password

• Confirm password

After Signup

1. A verification email will be sent

2. Open your inbox

3. Click the verification link

4. Your account becomes active

You cannot access the dashboard or create projects until your email is verified.

2. Login

Once your account is verified:

1. Open the login page

2. Enter your email and password

3. Access the dashboard

After login, you will be redirected to your workspace.

3. Create Your First Project

Before sending events, you must create a project. A project represents the system or platform connected to Trichspace.

Examples

• Shopping platform

• Education platform

• Events platform

• Fintech platform

• Wellness application

Each Project Has

• Its own API keys

• Independent event streams

• Independent rules

• Independent websocket connection

• Independent webhooks

Required Fields

Project Management

• Create project

• Update project

• Delete project

• View project details

4. Dashboard Navigation

Once a project is selected, the dashboard displays:

• Overview

• Events

• Rules

• API Keys

• Settings

• Webhooks

Each section is connected only to the selected project.

5. Overview

The Overview section provides a real-time summary of your project activity including:

• Total events processed

• Recent activity

• Reward statistics

• Processing activity

• Live event monitoring

• Project performance metrics

6. Events

The Events section displays all incoming events from your platform:

• Raw events from your system

• Internal engine processing events

• Reward events

• Rule evaluation events

• Processing status updates

Event Table Fields

• Event ID

• Event name

• Actor ID

• Status

• Payload

• Metadata

• Created timestamp

Open a single event by its ID to inspect the full payload, rule matches, processing lifecycle, and decision outcome.

7. Rules

Rules define behavior and expected outcomes — the core intelligence layer of Trichspace.

Rules Determine

• What behavior matters

• What patterns should be detected

• What outcome should happen

Rule Management

• Create, update, delete rules

• Enable / disable rules

• View rule history

• Visual UI editor and JSON editor

Rule Example 1 — Sequence

{
  "name": "Onboarding Complete v2",
  "when_condition": {
    "sequence": [
      "tutorial_completed",
      "quiz_passed",
      "lesson_completed"
    ]
  },
  "then_action": {
    "reward": "onboarding_complete"
  },
  "enabled": true
}

Rule Example 2 — Count

{
                "name": "3 lessons badge",
                "when_condition": {
                  "event": "lesson_completed",
                  "count": 3
                },
                "then_action": {
                  "reward": "bronze_badge"
                },
                "enabled": true
}

Rule Example 3

{
  "name": "Learning Starter",
  "when_condition": {
    "event": "lesson_completed",
    "count": 5
  },
  "then_action": {
    "reward": "learning_starter"
  },
  "enabled": true
}

8. API Keys & Settings

The Settings section allows you to manage project details, API keys, metadata, and configuration.

Available Actions

• Edit project name and description

• View project keys

• Regenerate API keys

• View websocket configuration

Each project contains independent API credentials.

9. Webhooks

Webhooks allow Trichspace to notify your system whenever a rule or reward is triggered. A webhook can be attached to any rule (optional).

Webhook Management

• Create, update, delete webhooks

• Enable / disable webhooks

Webhook URL Example

https://learnflow.com/api/rewards

Example Webhook Payload

{
  "event": "reward_generated",
  "actor_id": "user_123",
  "rule_id": "rule_learning_starter",
  "reward": {
    "name": "learning_starter",
    "points": 20
  },
  "project_id": "proj_123",
  "timestamp": "2026-05-08T20:21:01Z"
}

10. Real-Time Monitoring

Every project is automatically connected to the Trichspace websocket infrastructure, enabling live events, rewards, rule processing, and dashboards. No additional setup required.

11. Custom Socket Connection (Optional)

If you opt out of the Trichspace dashboard sockets, you can build your own websocket client. Authentication uses the project API key.

WebSocket Connection

const socket = new WebSocket(
  "wss://api.trichspace.com/socket?x-api-key=YOUR_PROJECT_API_KEY"
)

socket.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log(data)
}

Example Real-Time Payload

{
  "type": "reward_generated",
  "actor_id": "user_123",
  "event_name": "lesson_completed",
  "reward": {
    "points": 20,
    "name": "learning_starter"
  }
}

12. Sending Events to Trichspace

Once your project and rules are configured, your platform can begin sending events. Trichspace supports any platform capable of making HTTP requests.

API Endpoint

POST /api/v1/events

Required Headers

x-api-key: YOUR_PROJECT_API_KEY
content-type: application/json

Event Payload

{
  "actor_id": "user_123",
  "name": "lesson_completed",
  "payload": {
    "lesson_id": "intro-to-programming",
    "score": 95,
    "duration_seconds": 300
  },
  "metadata": {
    "device": "mobile",
    "platform": "ios"
  }
}

Payload Fields

Example API Request

await fetch("https://api.trichspace.com/api/v1/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_PROJECT_API_KEY"
  },
  body: JSON.stringify({
    actor_id: "user_123",
    name: "lesson_completed",
    payload: {
      lesson_id: "intro-to-programming",
      score: 95,
      duration_seconds: 300
    },
    metadata: {
      device: "mobile",
      platform: "ios"
    }
  })
})

Example Response

{
  "data": {
    "id": "6605454d-4b6e-46f9-b4f5-3b15a632fbf5",
    "name": "lesson_completed",
    "status": "pending",
    "metadata": { "device": "mobile", "platform": "ios" },
    "project_id": "dad8de66-fe88-44ad-8861-adcbc2234b89",
    "payload": {
      "duration_seconds": 300,
      "lesson_id": "intro-to-programming",
      "score": 95
    },
    "actor_id": "user_123",
    "inserted_at": "2026-05-08T20:21:01Z",
    "updated_at": "2026-05-08T20:21:01Z"
  },
  "success": true
}

Processing Statuses

Understanding Actor IDs

The actor_id represents the entity performing the action — a user, student, device, wallet, machine, or customer.

{
  "actor_id": "student_001"
}

Best Practices

Use Clear Event Names

Good examples: lesson_completed, payment_failed, onboarding_completed

Avoid: event_1, test_event, random_action

Keep Payloads Focused

Send only relevant data. Avoid large unnecessary payloads.

Design Rules Carefully

Rules define system intelligence. Be specific and intentional when defining desired behavior, expected outcomes, reward logic, and recovery flows.