Quick Start

1. Create an account

Go to provenance-web.onrender.com/signup and create your organization. You'll need:

An organization name (e.g., "Acme Inc.")
Your email and password

After signup, you'll receive an API key. Save it — it won't be shown again.

2. Set up your building blocks

Create a resource type, action, and origin. These are the three dimensions every interaction references.

# 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", "mnemonic": "USER"}'

# 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"}'

# 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"}'

3. Record an interaction

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"
    }
  }'

The API resolves the mnemonics (USER, CREATE, WEBAPP) to their UUIDs automatically.

4. Query it back

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

Or use the CLI

Install the CLI and configure it once:

npm install -g @stdiolabs/provenance-cli

provenance config set apiUrl https://provenance.onrender.com/api
provenance config set apiKey your-api-key
provenance config set origin MY-SERVICE

Then track interactions with mnemonics:

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

Search:

provenance search -r user-123

View the trace:

provenance trace user-123

Or use the SDK

npm install @stdiolabs/provenance-sdk

Record interactions 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',
  interaction: { email: 'user@example.com' },
});

Or use the full REST API client:

const api = await provenance.api();
const trace = await api.traces.get('user-123');
const actions = await api.actions.list();

The SDK handles queue ingestion, API access, retries, credential caching, and auto-pagination. A C# SDK is coming soon.

What's next

Configuration — API base URL, rate limits, and API key management
First Interaction — Detailed walkthrough of the interaction model
Resource Types — Design your resource type taxonomy