Interactions

Interactions are the core data model — every event in your system is recorded as an interaction.

Creating an interaction

POST /api/interactions

You can use mnemonics or UUIDs for resource type, action, and origin. Mnemonics are recommended — they're human-readable and the API resolves them automatically.

Using mnemonics

{
  "resourceId": "order-456",
  "resourceType": "ORDER",
  "action": "CREATE",
  "origin": "WEBAPP",
  "interaction": {
    "total": 149.99,
    "currency": "USD",
    "items": 3
  },
  "externalReference": "stripe-pi-abc123"
}

Using UUIDs

{
  "resourceId": "order-456",
  "resourceTypeId": "a1b2c3d4-...",
  "actionId": "e5f6a7b8-...",
  "originId": "i9j0k1l2-...",
  "interaction": {
    "total": 149.99
  }
}

If you provide both a mnemonic and a UUID for the same field, they must match or the request is rejected.

Request fields

Field	Required	Description
`resourceId`	Yes	Your resource's identifier (any string)
`resourceType`	*	Resource type mnemonic
`resourceTypeId`	*	Resource type UUID
`action`	*	Action mnemonic
`actionId`	*	Action UUID
`origin`	*	Origin mnemonic
`originId`	*	Origin UUID
`interaction`	No	Freeform JSON metadata — any shape you want
`externalReference`	No	External system reference (e.g., Stripe payment ID)
`externalResponse`	No	External system response data

* Provide either the mnemonic or the UUID for each — at least one is required.

Request headers

Header	Required	Description
`x-api-key`	Yes	API key for authentication
`x-uowid`	No	Unit of Work ID — auto-generated UUID if not provided
`x-userid`	No	User ID performing the interaction
`x-interaction-timestamp`	No	Custom timestamp (defaults to current time)

Response

{
  "interactionId": "f1e2d3c4-...",
  "interactionNumber": 42,
  "resourceId": "order-456",
  "resourceTypeId": "a1b2c3d4-...",
  "actionId": "e5f6a7b8-...",
  "originId": "i9j0k1l2-...",
  "interaction": { "total": 149.99, "currency": "USD", "items": 3 },
  "externalReference": "stripe-pi-abc123",
  "uowId": "550e8400-...",
  "userId": null,
  "createdDate": "2024-01-15T10:30:00.000Z",
  "interactionTimestamp": null
}

The interactionNumber is an auto-incrementing sequence — useful for ordering and gap detection.

Querying interactions

GET /api/interactions

All queries return paginated results with joined mnemonic data.

Query parameters

Parameter	Description
`resourceId`	Filter by resource ID
`interactionId`	Filter by interaction ID
`uowId`	Filter by Unit of Work ID
`externalReference`	Filter by external reference
`userId`	Filter by user ID
`action`	Filter by action mnemonic
`resourceType`	Filter by resource type mnemonic
`origin`	Filter by origin mnemonic
`startDate`	Interactions created on or after this date
`endDate`	Interactions created on or before this date
`page`	Page number (default: `1`)
`limit`	Items per page (default: `50`, max: `100`)

Response shape

{
  "data": [
    {
      "interactionId": "...",
      "interactionNumber": 42,
      "resourceId": "order-456",
      "resourceTypeId": "...",
      "actionId": "...",
      "originId": "...",
      "resourceTypeMnemonic": "ORDER",
      "resourceTypeIcon": "📦",
      "resourceTypeFontColorHex": "#fff",
      "resourceTypeBgColorHex": "#f59e0b",
      "actionMnemonic": "CREATE",
      "actionIcon": "➕",
      "originMnemonic": "WEBAPP",
      "originIcon": "🌐",
      "interaction": { "total": 149.99 },
      "uowId": "...",
      "userId": null,
      "createdDate": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Every interaction includes the mnemonic, icon, and color data for its resource type, action, and origin — so the UI can render rich badges without extra lookups.

Examples

# All interactions for a resource
GET /api/interactions?resourceId=order-456

# Filter by action and type
GET /api/interactions?action=CREATE&resourceType=ORDER

# Date range
GET /api/interactions?startDate=2024-01-01&endDate=2024-01-31

# Paginated
GET /api/interactions?page=2&limit=25

# By Unit of Work
GET /api/interactions?uowId=550e8400-...

Timeline

Get daily interaction counts for visualization:

# Last 90 days (uses materialized view — fast)
GET /api/interactions/timeline?days=90

# Custom range with auto-detected granularity
GET /api/interactions/timeline?startDate=2024-01-01&endDate=2024-01-31

# Explicit granularity
GET /api/interactions/timeline?startDate=2024-01-01&endDate=2024-01-02&granularity=hour

Granularity options: 15 minutes, hour, 6 hours, day.

Activity search

For complex queries across multiple resources, use the activity endpoint:

POST /api/activity

{
  "resources": [
    { "resourceId": "order-456", "resourceType": "ORDER" },
    { "resourceId": "payment-789", "resourceType": "PAYMENT" }
  ],
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z"
}

Returns activity grouped by userId and uowId, with interaction counts and time ranges for each group.

Traces

View all interactions linked by a Unit of Work ID:

GET /api/traces/:uowId

Returns all interactions for that UOW in chronological order.

Timeline view

Get a simplified chronological view with key fields only:

GET /api/traces/:uowId/timeline

Summary

Get aggregated statistics for a trace:

GET /api/traces/:uowId/summary

Returns total interactions, duration, unique actions, resource types, origins, and resource count.

API reference

Method	Endpoint	Description
`GET`	`/api/interactions`	List with filtering and pagination
`GET`	`/api/interactions/:id`	Get by ID
`POST`	`/api/interactions`	Create
`GET`	`/api/interactions/timeline`	Daily counts for visualization
`POST`	`/api/interactions/timeline/refresh`	Refresh materialized view
`POST`	`/api/activity`	Activity search across multiple resources
`GET`	`/api/traces/:uowId`	Trace by Unit of Work ID
`GET`	`/api/traces/:uowId/timeline`	Timeline view of trace
`GET`	`/api/traces/:uowId/summary`	Aggregated trace statistics

On this page