Unit of Work

A Unit of Work (UOW) is a UUID that links related interactions together — even when they happen in different services at different times.

How it works

Pass the x-uowid header on every interaction that belongs to the same logical operation:

# Service A: Create order
curl -X POST https://provenance.onrender.com/api/interactions \
  -H "x-api-key: your-api-key" \
  -H "x-uowid: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceId": "order-789",
    "resourceType": "ORDER",
    "action": "CREATE",
    "origin": "WEBAPP",
    "interaction": { "total": 99.99 }
  }'

# Service B: Process payment
curl -X POST https://provenance.onrender.com/api/interactions \
  -H "x-api-key: your-api-key" \
  -H "x-uowid: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceId": "payment-456",
    "resourceType": "PAYMENT",
    "action": "PROCESS",
    "origin": "PAYMENT_SVC",
    "interaction": { "method": "card", "last4": "4242" }
  }'

# Service C: Update inventory
curl -X POST https://provenance.onrender.com/api/interactions \
  -H "x-api-key: your-api-key" \
  -H "x-uowid: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceId": "sku-001",
    "resourceType": "INVENTORY",
    "action": "UPDATE",
    "origin": "INVENTORY_SVC",
    "interaction": { "quantity": -1 }
  }'

All three interactions are now linked by the same UOW ID.

If you don't provide x-uowid, the API generates one automatically. This means every interaction always has a UOW ID — you just need to provide your own when you want to correlate multiple interactions.

Querying by UOW

Find all interactions in a unit of work:

GET /api/interactions?uowId=550e8400-e29b-41d4-a716-446655440000

Or via the activity endpoint:

POST /api/activity
{
  "resources": [
    { "resourceId": "550e8400-e29b-41d4-a716-446655440000", "resourceType": "ORDER" }
  ]
}

Using the CLI

# Generate a UOW ID
UOWID=$(provenance uow new)

# Use it across multiple track commands
provenance track -r order-789 -t ORDER -a CREATE -u $UOWID \
  -d '{"total":99.99}'

provenance track -r payment-456 -t PAYMENT -a PROCESS -u $UOWID \
  -d '{"method":"card"}'

provenance track -r sku-001 -t INVENTORY -a UPDATE -u $UOWID \
  -d '{"quantity":-1}'

Using the SDK

Queue ingestion

const { v4: uuidv4 } = require('uuid');

const uowId = uuidv4();

await provenance.log({
  resourceType: 'order', resourceId: 'order-789',
  action: 'create', uowId,
  interaction: { total: 99.99 }
});

await provenance.log({
  resourceType: 'payment', resourceId: 'payment-456',
  action: 'process', uowId,
  interaction: { method: 'card' }
});

REST API client

const api = await provenance.api();

// Find all interactions in a unit of work
const results = await api.activity.search({
  filters: { uowId: '550e8400-e29b-41d4-a716-446655440000' },
});

When to use UOW

Multi-step transactions — order → payment → fulfillment → notification
CI/CD pipelines — build → test → deploy → verify
Data pipelines — extract → transform → load → validate
User journeys — signup → verify email → complete profile → first login
Any operation that spans multiple services or resources