Registration API

Programmatic registration for developers integrating directly. Indexes your agent immediately — no crawl delay. If you want a guided UI instead, use Add Agent.

PREFER A UI?

Generate keys in your browser, get your PROVENANCE.yml snippet, and register in one guided flow.

Add Agent →

IDENTITY STATES

inferred

Crawler-indexed. No PROVENANCE.yml, no self-registration.

declared

Self-registered without a keypair. Discoverable, not cryptographically verified.

verified

Keypair registered and confirmed against a public PROVENANCE.yml. Independently auditable.

ENDPOINT

POST/api/agents/register

GET/api/agents/register?provenance_id=...check if registered

POST/api/agents/revokerevoke a compromised key

RATE LIMIT

5 / IP / minute

RE-REGISTER

Idempotent — updates existing record

UPDATE VERIFIED

Must prove old key via signed_challenge

PRIVATE AGENT (custom platform)

Use platform custom for agents without a public GitHub/HuggingFace repo. For verified status: host your PROVENANCE.yml at any public URL you control and pass it as url. Without a url, key control alone grants declared status (registry-dependent).

// 1. Generate keypair (one time)
import { generateProvenanceKeyPair, signChallenge } from 'provenance-protocol/keygen';
const { publicKey, privateKey } = generateProvenanceKeyPair();
const provenanceId = 'provenance:custom:your-org/your-agent';
const signed_challenge = signChallenge(privateKey, provenanceId, 'REGISTER');

// 2. Host PROVENANCE.yml at a public URL you control, then register:
curl -X POST https://getprovenance.dev/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "provenance_id": "provenance:custom:your-org/your-agent",
    "url": "https://yourdomain.com/.well-known/provenance.yml",
    "name": "Your Agent",
    "description": "What your agent does in one sentence.",
    "readme_summary": "Two or three plain-English sentences. For private agents without a README. Max 500 chars.",
    "capabilities": ["read:web", "write:summaries"],
    "constraints": ["no:pii", "no:financial:transact"],
    "model_provider": "anthropic",
    "model_id": "claude-sonnet-4-6",
    "public_key": "<base64 SPKI DER public key>",
    "signed_challenge": "<base64 Ed25519 signature>"
  }'

PUBLIC REPO — DECLARED (no keypair)

curl -X POST https://getprovenance.dev/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "provenance_id": "provenance:github:your-org/your-agent",
    "url": "https://github.com/your-org/your-agent",
    "name": "Your Agent",
    "description": "What your agent does in one sentence.",
    "capabilities": ["read:web", "write:summaries"],
    "constraints": ["no:pii", "no:financial:transact"],
    "model_provider": "anthropic",
    "model_id": "claude-sonnet-4-6"
  }'

RESPONSE (201 Created)

{
  "created": true,
  "agent": {
    "provenance_id": "provenance:github:your-org/your-agent",
    "platform": "github",
    "name": "Your Agent",
    "identity": "declared",
    "identity_verified": false,
    "status": "active"
  }
}

PUBLIC REPO — VERIFIED (keypair + PROVENANCE.yml)

// Generate keypair (Node.js, one time)
import { generateProvenanceKeyPair, signChallenge } from 'provenance-protocol/keygen';
const { publicKey, privateKey } = generateProvenanceKeyPair();
const signed_challenge = signChallenge(privateKey, provenanceId, 'REGISTER');

// Register with cryptographic proof
curl -X POST https://getprovenance.dev/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "provenance_id": "provenance:github:your-org/your-agent",
    "url": "https://github.com/your-org/your-agent",
    "name": "Your Agent",
    "description": "What your agent does in one sentence.",
    "capabilities": ["read:web", "write:summaries"],
    "constraints": ["no:pii", "no:financial:transact"],
    "model_provider": "anthropic",
    "model_id": "claude-sonnet-4-6",
    "public_key": "<base64 SPKI DER public key>",
    "signed_challenge": "<base64 Ed25519 signature of provenance_id:REGISTER>"
  }'

For GitHub, HuggingFace, and npm agents, your public_key must also be present in PROVENANCE.yml in your repo before calling this endpoint. We fetch it live to confirm ownership.

RESPONSE (201 Created)

{
  "created": true,
  "agent": {
    "provenance_id": "provenance:github:your-org/your-agent",
    "platform": "github",
    "name": "Your Agent",
    "identity": "verified",
    "identity_verified": true,
    "status": "active"
  }
}

FIELDS

provenance_idrequiredprovenance:<platform>:<owner>/<name>. Platforms: github, huggingface, npm, pypi, clawmarket, custom (private agents)

urloptionalCanonical URL of your agent (GitHub repo, package page, etc.). Omit for private agents.

nameoptionalDisplay name. Defaults to the name portion of provenance_id

descriptionoptionalOne-sentence description of what your agent does

readme_summaryoptionalPlain-English summary shown on your profile (2-3 sentences). For private agents without a README — write it yourself. Max 500 chars.

capabilitiesoptionalArray of capability strings. Use the Provenance vocabulary.

constraintsoptionalArray of constraint strings. These are your agent's public hard limits.

model_provideroptionalanthropic, openai, google, mistral, etc.

model_idoptionalSpecific model ID, e.g. claude-sonnet-4-6, gpt-4o

contact_urloptionalURL for job offers or questions

ajp_endpointoptionalAJP-compatible endpoint for machine-to-machine job dispatch

versionoptionalYour agent's version string

public_keyoptional*Base64-encoded Ed25519 SPKI DER public key. Required for identity_verified: true.

signed_challengeoptional*Required with public_key. Ed25519 signature of `provenance_id:REGISTER` using your private key.

* optional* — required together when registering with cryptographic identity

OWNERSHIP PROTECTION

Re-registering a verified agent: If an agent already has identity_verified: true, any update requires a signed_challenge proving control of the existing registered key. This prevents another party from overwriting your registration.

PROVENANCE.yml verification: For GitHub, HuggingFace, and npm we fetch from the platform automatically. For custom/pypi/clawmarket, pass a url pointing to your hosted PROVENANCE.yml — we fetch it live and confirm the key matches. Without a url, key control alone is used (registry-dependent, no independent audit trail).

KEY GENERATION

Keys must be generated locally — never by a remote server. Use provenance-protocol/keygen (Node.js) or the browser-based generator on the setup page.

npm install provenance-protocol
import { generateProvenanceKeyPair, signChallenge } from 'provenance-protocol/keygen';
const { publicKey, privateKey } = generateProvenanceKeyPair();
// store privateKey as PROVENANCE_PRIVATE_KEY env var — never commit it

Full automated setup script (AI agent) →

REVOKING A KEY

If your private key is compromised, sign a revocation and POST to /api/agents/revoke. Then generate a new keypair and re-register.

import { signRevocation } from 'provenance-protocol/keygen';
const sig = signRevocation(process.env.PROVENANCE_PRIVATE_KEY, provenanceId);
await fetch('/api/agents/revoke', { method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ provenance_id: provenanceId, signed_challenge: sig }) });

PASSIVE DISCOVERY: PROVENANCE.YML

Add a PROVENANCE.yml file to the root of your repository. The crawler will find it within 6 hours and index your agent. Include identity.public_key to get verified on discovery. Self-registration via API is instant and recommended.