Track Event

Submit a structured event to be memorized.

POST /events

Request Body

{
  "appId": string,           // Required: Your app identifier
  "userId": string,          // Required: User this event relates to
  "eventType": string,       // Required: Type of event
  "source": string,          // Required: Event source
  "timestamp": string,       // Required: ISO 8601 timestamp
  "data": object,            // Required: Event-specific data
  "suggestedCategory"?: string,
  "suggestedEntities"?: Array<{ name: string, type: string }>,
  "importance"?: "low" | "medium" | "high" | "critical"
}

Example Request

curl -X POST https://api.magneteco.io/v1/events \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "tanda",
    "userId": "user-123",
    "eventType": "sow_approved",
    "source": "tanda-app",
    "timestamp": "2024-01-15T14:30:00Z",
    "data": {
      "sowTitle": "Phase 1 Implementation",
      "projectName": "NetSuite Migration",
      "clientName": "Acme Corp",
      "approverName": "Jane Smith"
    },
    "importance": "high"
  }'

await memory.trackEvent({
  userId: 'user-123',
  eventType: 'sow_approved',
  data: {
    sowTitle: 'Phase 1 Implementation',
    projectName: 'NetSuite Migration',
    clientName: 'Acme Corp',
    approverName: 'Jane Smith',
  },
  importance: 'high',
});

Response

{
  "status": "queued",
  "eventId": "evt-123"
}

Event Templates

Events are transformed to natural language using templates before extraction:

// Event
{
  eventType: 'sow_approved',
  data: { sowTitle: 'Phase 1', approverName: 'Jane' }
}

// Transformed to:
"SOW 'Phase 1' was approved by Jane. Project can proceed to execution."

Importance Levels

Level	Description	Processing
`low`	Informational	Normal processing, lower retrieval priority
`medium`	Standard events	Normal processing
`high`	Important events	Higher confidence score, flagged in summaries
`critical`	Must not be forgotten	Highest confidence, never pruned

Example Events

Project Management

await memory.trackEvent({
  userId: 'user-123',
  eventType: 'deadline_missed',
  data: {
    itemType: 'milestone',
    itemName: 'Phase 1 Delivery',
    projectName: 'NetSuite Migration',
    dueDate: '2024-01-15',
    daysOverdue: 3,
    clientName: 'Acme Corp',
  },
  importance: 'critical',
});

Financial

await memory.trackEvent({
  userId: 'user-789',
  eventType: 'budget_exceeded',
  data: {
    accountCode: '6100',
    accountName: 'Marketing Expenses',
    budgetAmount: 50000,
    actualAmount: 52340,
    percentOver: 4.68,
    period: 'January 2024',
  },
  suggestedCategory: 'budget_alerts',
  importance: 'high',
});

Integration

await memory.trackEvent({
  userId: 'company-abc',
  eventType: 'data_source_connected',
  data: {
    sourceName: 'QuickBooks Online',
    sourceType: 'accounting',
    connectionStatus: 'active',
    recordsImported: 1247,
  },
  importance: 'medium',
});

Batch Events

For high-volume scenarios:

await memory.trackEvents([
  { userId: 'user-1', eventType: 'test_passed', data: { ... } },
  { userId: 'user-1', eventType: 'test_passed', data: { ... } },
  { userId: 'user-2', eventType: 'sow_approved', data: { ... } },
]);

Events

On this page