First Interaction

This guide walks through the interaction model in detail. If you just want to get started quickly, see Quick Start.

The building blocks

Every interaction references three things:

Concept	What it is	Example
Resource Type	Category of thing being tracked	`USER`, `ORDER`, `DEPLOYMENT`
Action	Operation performed	`CREATE`, `UPDATE`, `DELETE`, `LOGIN`
Origin	Where it came from	`WEBAPP`, `CLI`, `GITHUB_ACTIONS`

You can create these explicitly, or just use mnemonics in your interaction and let the API resolve them.

Step 1: Set up your building blocks

Create a resource type

curl -X POST https://provenance.onrender.com/api/resource-types \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "title": "User Account",
    "description": "User account resource",
    "mnemonic": "USER",
    "icon": "👤",
    "fontColorHex": "#ffffff",
    "bgColorHex": "#3b82f6"
  }'

Response:

{
  "resourceTypeId": "a1b2c3d4-...",
  "title": "User Account",
  "description": "User account resource",
  "mnemonic": "USER",
  "icon": "👤",
  "fontColorHex": "#ffffff",
  "bgColorHex": "#3b82f6",
  "isSystem": false,
  "createdDate": "2024-01-15T10:00:00.000Z",
  "modifiedDate": "2024-01-15T10:00:00.000Z"
}

Create an action

curl -X POST https://provenance.onrender.com/api/actions \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "title": "Create",
    "mnemonic": "CREATE",
    "icon": "➕",
    "bgColorHex": "#22c55e"
  }'

Create an origin

curl -X POST https://provenance.onrender.com/api/origins \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "title": "Web Application",
    "mnemonic": "WEBAPP",
    "icon": "🌐"
  }'

Step 2: Record an interaction

You can use mnemonics (recommended) or UUIDs:

Using mnemonics

curl -X POST https://provenance.onrender.com/api/interactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "resourceId": "user-123",
    "resourceType": "USER",
    "action": "CREATE",
    "origin": "WEBAPP",
    "interaction": {
      "email": "user@example.com",
      "plan": "starter"
    }
  }'

Using UUIDs

curl -X POST https://provenance.onrender.com/api/interactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "resourceId": "user-123",
    "resourceTypeId": "a1b2c3d4-...",
    "actionId": "e5f6a7b8-...",
    "originId": "i9j0k1l2-...",
    "interaction": {
      "email": "user@example.com",
      "plan": "starter"
    }
  }'

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 — at least one is required.

Optional headers

Header	Description
`x-uowid`	Unit of Work ID — auto-generated UUID if not provided
`x-userid`	User ID performing the interaction
`x-interaction-timestamp`	Custom timestamp (defaults to now)

Step 3: Query it back

curl -H "x-api-key: your-api-key" \
  "https://provenance.onrender.com/api/interactions?resourceId=user-123"

Response:

{
  "data": [
    {
      "interactionId": "...",
      "interactionNumber": 1,
      "resourceId": "user-123",
      "resourceTypeId": "...",
      "actionId": "...",
      "originId": "...",
      "resourceTypeMnemonic": "USER",
      "resourceTypeIcon": "👤",
      "resourceTypeBgColorHex": "#3b82f6",
      "actionMnemonic": "CREATE",
      "actionIcon": "➕",
      "originMnemonic": "WEBAPP",
      "originIcon": "🌐",
      "interaction": {
        "email": "user@example.com",
        "plan": "starter"
      },
      "uowId": "...",
      "createdDate": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Interactions are returned with joined mnemonics, icons, and colors — so the UI can render rich badges without extra lookups.

Using the CLI

provenance track -r user-123 -t USER -a CREATE -d '{"email":"user@example.com"}'
provenance search -r user-123
provenance trace user-123

Using the SDK

Record via the managed queue:

const { create } = require('@stdiolabs/provenance-sdk');

const provenance = await create({ apiKey: 'your-api-key', origin: 'my-service' });

await provenance.log({
  resourceType: 'USER',
  resourceId: 'user-123',
  action: 'CREATE',
  uowId: crypto.randomUUID(),
  interaction: { email: 'user@example.com', plan: 'starter' },
});

Or use the REST API client:

const api = await provenance.api();

// Query it back
const interactions = await api.interactions.list({ resourceId: 'user-123' });

// Get the trace
const trace = await api.traces.get('user-123');

A C# SDK is coming soon — see SDKs.

Next steps

Resource Types — Design your resource type taxonomy
Interactions — Full query parameters and filtering
Unit of Work — Correlate related interactions across services

On this page