> ## Documentation Index
> Fetch the complete documentation index at: https://docs.provenancekit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Record your first provenance event in under 5 minutes.

> 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

* Node.js 18+
* A running `provenancekit-api` instance (see [self-hosting](#self-hosting)) — or a project API key from [app.provenancekit.com](https://app.provenancekit.com)

## 1. Install the SDK

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
npm install @provenancekit/sdk
# or
pnpm add @provenancekit/sdk
```

## 2. Create a client

```ts theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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.

```ts theme={"theme":{"light":"github-dark","dark":"github-dark"}}
// 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:

```ts theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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

```ts theme={"theme":{"light":"github-dark","dark":"github-dark"}}
// 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

<Columns cols={2}>
  <Card title="Recording Provenance" icon="pen" href="/guides/recording-provenance">
    Deeper dive into the file(), entity(), and attribution APIs.
  </Card>

  <Card title="AI Extension" icon="cpu" href="/guides/ai-extension">
    Capture full AI metadata: model, tokens, prompt hash, session.
  </Card>

  <Card title="Extensions overview" icon="puzzle-piece" href="/guides/extensions">
    All 15 built-in extensions and when to use them.
  </Card>

  <Card title="On-chain anchoring" icon="link" href="/protocol/contracts">
    Anchor provenance records on an EVM chain.
  </Card>
</Columns>

## Self-hosting

To run the API locally:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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.