API Reference - ProvenanceKit

The ProvenanceKit API has two namespaces with separate authentication: /v1/* for provenance operations and /management/* for the control plane.

Base URL

https://api.provenancekit.com
# or your self-hosted instance:
http://localhost:3001

Authentication

Provenance endpoints (`/v1/*`)

Use a pk_live_ project API key as a Bearer token:

curl https://api.provenancekit.com/v1/entity \
  -H "Authorization: Bearer pk_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"role":"human","name":"Alice"}'

API keys are created in the dashboard or via the management API. Keys are scoped to a project and shown only once on creation.

Management endpoints (`/management/*`)

Use the MANAGEMENT_API_KEY shared secret plus an X-User-Id header identifying the user:

curl https://api.provenancekit.com/management/orgs \
  -H "Authorization: Bearer <MANAGEMENT_API_KEY>" \
  -H "X-User-Id: user_privy_did_here"

Core endpoints

Entities

Method	Path	Description
`POST`	`/v1/entity`	Create or retrieve an entity
`GET`	`/v1/entity/:id`	Get entity by ID
`GET`	`/v1/entities`	List entities (filter by role, pagination)

Actions

Method	Path	Description
`POST`	`/v1/action`	Record a provenance action
`GET`	`/v1/action/:id`	Get action by ID
`GET`	`/v1/actions`	List actions (filter by type, sessionId, performedBy)

Attributions

Method	Path	Description
`POST`	`/v1/attribution`	Create an attribution
`GET`	`/v1/attributions`	List attributions (filter by actionId, entityId)

Bundles

Method	Path	Description
`GET`	`/v1/bundle/:cid`	Full provenance bundle for a CID (entities + actions + attributions)

Management

Method	Path	Description
`GET`	`/management/orgs`	List orgs for authenticated user
`GET`	`/management/orgs/:slug`	Get org by slug
`POST`	`/management/orgs`	Create org
`GET`	`/management/projects/:orgSlug`	List projects in an org
`POST`	`/management/projects`	Create project
`GET`	`/management/api-keys/:projectId`	List API keys for a project
`POST`	`/management/api-keys`	Create API key
`DELETE`	`/management/api-keys/:id`	Revoke API key
`POST`	`/management/auth/validate-key`	Validate a pk_live_ key (system use)

SDKs

The TypeScript SDK wraps all /v1/* endpoints:

npm install @provenancekit/sdk

See the Quickstart for usage examples.

OpenAPI spec

🚧 A full OpenAPI specification is planned. For now, use the SDK or the endpoint reference above.

​Base URL

​Authentication

​Provenance endpoints (/v1/*)

​Management endpoints (/management/*)

​Core endpoints

​Entities

​Actions

​Attributions

​Bundles

​Management

​SDKs

​OpenAPI spec