Skip to main content
This guide uses the ProvenanceKit SDK against a self-hosted or cloud API instance. You’ll create an entity, record an action, and query the result.

​
Prerequisites

​
1. Install the SDK

npm install @provenancekit/sdk
# or
pnpm add @provenancekit/sdk

​
2. Create a client

import { ProvenanceKit } from "@provenancekit/sdk";

const pk = new ProvenanceKit({
  apiKey: process.env.PK_API_KEY!,   // pk_live_... key from your project settings
  apiUrl: process.env.PK_API_URL ?? "https://api.provenancekit.com",
});

​
3. Register entities

Entities represent participants. Register them once and reuse their IDs. 
// Register the human author
const humanId = await pk.entity({
  role: "human",
  name: "Alice Chen",
});

// Register the AI agent
const aiId = await pk.entity({
  role: "ai",
  name: "GPT-4o",
  aiAgent: {
    model: { provider: "openai", model: "gpt-4o" },
    autonomyLevel: "supervised",
    delegatedBy: humanId,
  },
});

​
4. Record an action

When your AI pipeline runs, record what happened: 
import { createHash } from "crypto";

const prompt = "Write a product description for noise-cancelling headphones.";
const output = "Experience pure silence with ProSound ANC headphones...";

// Content-addressed IDs — use IPFS CIDs in production
const promptCid = "sha256:" + createHash("sha256").update(prompt).digest("hex");
const outputCid = "sha256:" + createHash("sha256").update(output).digest("hex");

const actionId = await pk.file({
  type: "file.create",
  performedBy: aiId,
  inputs: [{ cid: promptCid }],
  cid: outputCid,
  sessionId: "sess_my_pipeline_run",
  extensions: {
    "ext:ai@1.0.0": {
      provider: "openai",
      model: "gpt-4o",
      promptHash: promptCid,
      tokensUsed: 320,
    },
  },
  attributions: [
    {
      entityId: humanId,
      role: "prompter",
      confidence: 1.0,
    },
  ],
});

console.log("Action recorded:", actionId);

​
5. Query the provenance

// Get the full provenance bundle for a CID
const bundle = await pk.getBundle(outputCid);

console.log("Entities:", bundle.entities.map(e => e.name));
console.log("Actions:", bundle.actions.map(a => a.type));
console.log("Attributions:", bundle.attributions.map(a => a.role));

​
What you built

In five steps you:
  1. Created typed entities (human + AI)
  2. Recorded a provenance action with AI metadata extension
  3. Linked the human as “prompter” via an attribution
  4. Queried the full bundle for the output CID
This data is now queryable, renderable in the ProvenanceGraph UI component, and (optionally) anchorable on-chain.

​
Next steps

Recording Provenance

Deeper dive into the file(), entity(), and attribution APIs.

AI Extension

Capture full AI metadata: model, tokens, prompt hash, session.

Extensions overview

All 15 built-in extensions and when to use them.

On-chain anchoring

Anchor provenance records on an EVM chain.

​
Self-hosting

To run the API locally: 
git clone https://github.com/Arttribute/provenancekit
cd provenancekit
pnpm install
cp apps/provenancekit-api/.env.example apps/provenancekit-api/.env
# Fill in DATABASE_URL, MANAGEMENT_API_KEY, etc.
pnpm --filter provenancekit-api dev
The API runs on http://localhost:3001 by default.