Skip to main content
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

MethodPathDescription
POST/v1/entityCreate or retrieve an entity
GET/v1/entity/:idGet entity by ID
GET/v1/entitiesList entities (filter by role, pagination)

​
Actions

MethodPathDescription
POST/v1/actionRecord a provenance action
GET/v1/action/:idGet action by ID
GET/v1/actionsList actions (filter by type, sessionId, performedBy)

​
Attributions

MethodPathDescription
POST/v1/attributionCreate an attribution
GET/v1/attributionsList attributions (filter by actionId, entityId)

​
Bundles

MethodPathDescription
GET/v1/bundle/:cidFull provenance bundle for a CID (entities + actions + attributions)

​
Management

MethodPathDescription
GET/management/orgsList orgs for authenticated user
GET/management/orgs/:slugGet org by slug
POST/management/orgsCreate org
GET/management/projects/:orgSlugList projects in an org
POST/management/projectsCreate project
GET/management/api-keys/:projectIdList API keys for a project
POST/management/api-keysCreate API key
DELETE/management/api-keys/:idRevoke API key
POST/management/auth/validate-keyValidate 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.