Kevros
Cryptographic governance for autonomous agents: precision decisioning, provenance attestation, intent binding, capability delegation, policy analysis, and compliance export.
Every decision gets a signed release token. Every action gets a hash-chained record. Every intent gets a cryptographic binding to its command. Downstream services verify independently — no callbacks, no trust assumptions.
Base URL: https://governance.taskhawktech.com
Quick Start
Get an API key (free, instant, no payment):
curl -X POST https://governance.taskhawktech.com/signup \
-H "Content-Type: application/json" \
-d '{"agent_id": "your-agent-id"}'
Response:
{
"api_key": "kvrs_...",
"tier": "free",
"monthly_limit": 1000,
"usage": {
"header": "X-API-Key"
}
}
Use the API key in all subsequent requests via the X-API-Key header.
Precision Decisioning
POST /governance/verify
Verify an action against policy bounds before execution. Returns ALLOW, CLAMP, or DENY with a cryptographic release token that any downstream service can verify independently.
Request:
{
"action_type": "api_call",
"action_payload": {
"endpoint": "/deploy",
"service": "api-v2",
"replicas": 3
},
"agent_id": "your-agent-id",
"policy_context": {
"max_values": { "replicas": 5 },
"forbidden_keys": ["sudo", "force"]
}
}
Response:
{
"decision": "ALLOW",
"verification_id": "a1b2c3d4-...",
"release_token": "f7a8b9c0...",
"applied_action": {
"endpoint": "/deploy",
"service": "api-v2",
"replicas": 3
},
"reason": "All values within policy bounds",
"epoch": 42,
"provenance_hash": "e3b0c442...",
"timestamp_utc": "2026-02-26T12:00:00Z"
}
- ALLOW — proceed as planned. The
release_token is proof.
- CLAMP — action was adjusted to safe bounds. Use
applied_action instead of your original.
- DENY — action rejected. Do not proceed.
release_token is null.
Share the release_token with collaborating agents so they can independently verify the decision.
Provenance Attestation
POST /governance/attest
Record a completed action in a hash-chained, append-only evidence ledger. Each attestation extends your provenance chain. Your raw payload is SHA-256 hashed — actual data is never stored.
Request:
{
"agent_id": "your-agent-id",
"action_description": "Deployed api-v2 with 3 replicas",
"action_payload": {
"service": "api-v2",
"replicas": 3,
"status": "success"
},
"context": {
"environment": "production",
"triggered_by": "scheduled"
}
}
Response:
{
"attestation_id": "b2c3d4e5-...",
"epoch": 43,
"hash_prev": "e3b0c442...",
"hash_curr": "a1b2c3d4...",
"timestamp_utc": "2026-02-26T12:00:01Z",
"chain_length": 43
}
A longer chain with consistent outcomes builds a higher trust score over time.
Intent Binding
POST /governance/bind
Bind a declared intent to a specific command. Creates a cryptographic link between what you plan to do and the command that does it. Prove later that you did exactly what you said you would.
Request:
{
"agent_id": "your-agent-id",
"intent_type": "MAINTENANCE",
"intent_description": "Scale api-v2 to handle traffic spike",
"command_payload": {
"action": "scale",
"service": "api-v2",
"replicas": 5
},
"goal_state": {
"replicas": 5,
"healthy": true
}
}
Response:
{
"intent_id": "c3d4e5f6-...",
"intent_hash": "d4e5f6a7...",
"binding_id": "e5f6a7b8-...",
"binding_hmac": "a7b8c9d0...",
"command_hash": "b8c9d0e1...",
"epoch": 44,
"timestamp_utc": "2026-02-26T12:00:02Z"
}
Save intent_id and binding_id to verify outcomes later.
Verify Outcome
POST /governance/verify-outcome
Verify whether a bound intent achieved its goal state. Free when used with a prior bind() call.
Request:
{
"agent_id": "your-agent-id",
"intent_id": "c3d4e5f6-...",
"binding_id": "e5f6a7b8-...",
"actual_state": {
"replicas": 5,
"healthy": true
},
"tolerance": 0.1
}
Response:
{
"verification_id": "f6a7b8c9-...",
"intent_id": "c3d4e5f6-...",
"status": "ACHIEVED",
"achieved_percentage": 100.0,
"discrepancy": null,
"evidence_hash": "c9d0e1f2...",
"timestamp_utc": "2026-02-26T12:00:03Z"
}
Status values: ACHIEVED, PARTIALLY_ACHIEVED, FAILED, BLOCKED, TIMEOUT. Free when used with a prior bind() call.
Compliance Bundle
POST /governance/bundle — $0.05 per call
Export your agent's full cryptographic trust record for compliance, auditing, or regulatory review.
Request:
{
"agent_id": "your-agent-id",
"time_range_start": "2026-02-25T00:00:00Z",
"time_range_end": "2026-02-26T12:00:00Z",
"include_intent_chains": true,
"include_pqc_signatures": true,
"include_verification_instructions": true
}
Response:
{
"bundle_id": "d4e5f6a7-...",
"agent_id": "your-agent-id",
"record_count": 42,
"truncated": false,
"chain_integrity": true,
"time_range": {"start": "2026-02-25T00:00:00Z", "end": "2026-02-26T12:00:00Z"},
"records": ["..."],
"intent_chains": ["..."],
"pqc_signatures": ["..."],
"verification_instructions": "Recompute SHA-256...",
"bundle_hash": "e5f6a7b8...",
"timestamp_utc": "2026-02-26T12:00:04Z"
}
Batch Operations
POST /governance/batch
Execute up to 100 governance operations (verify, attest, bind) in a single call. Each sub-operation is metered individually at standard rates. Use for bulk processing or multi-step workflows.
Request:
{
"agent_id": "your-agent-id",
"operations": [
{
"type": "verify",
"params": {
"action_type": "api_call",
"action_payload": {"endpoint": "/deploy", "replicas": 3}
}
},
{
"type": "attest",
"params": {
"action_description": "Deployment completed",
"action_payload": {"status": "success"}
}
}
],
"stop_on_deny": false
}
Response:
{
"batch_id": "g7h8i9j0-...",
"agent_id": "your-agent-id",
"total": 2,
"executed": 2,
"results": [
{"index": 0, "type": "verify", "status": "ok", "result": {"decision": "ALLOW", "...": "..."}},
{"index": 1, "type": "attest", "status": "ok", "result": {"attestation_id": "...", "...": "..."}}
],
"summary": {"allow": 1, "clamp": 0, "deny": 0, "attest": 1, "bind": 0, "error": 0},
"batch_hash": "a1b2c3d4..."
}
If stop_on_deny is true, processing halts on the first DENY decision.
Capability Delegation
POST /governance/delegate
Grant scoped, time-limited capabilities to another agent. The delegation is HMAC-signed and recorded in the provenance chain. Supports hierarchical sub-delegation with restrictive scope intersection.
Request:
{
"delegator_agent_id": "your-agent-id",
"delegatee_agent_id": "helper-agent-42",
"scope": {
"allowed_endpoints": ["verify", "attest"],
"policy_overrides": {"max_values": {"replicas": 3}},
"max_calls": 100
},
"ttl_seconds": 3600,
"description": "Handle deployment verification",
"allow_subdelegation": false
}
Response:
{
"delegation_id": "h8i9j0k1-...",
"delegation_token": "f7a8b9c0...",
"delegator_agent_id": "your-agent-id",
"delegatee_agent_id": "helper-agent-42",
"scope": {"allowed_endpoints": ["verify", "attest"], "max_calls": 100},
"expires_utc": "2026-02-26T13:00:00Z",
"provenance_hash": "b8c9d0e1...",
"chain_depth": 1
}
The delegatee passes the delegation_token as X-Delegate-Token header when acting on behalf of the delegator.
GET /governance/delegations/{agent_id} — list active delegations for an agent.
DELETE /governance/delegations/{delegation_id} — revoke an active delegation.
Reversibility Check
POST /governance/check-reversibility
Check whether an intent chain can be reversed. Pre-abort safety check for multi-step workflows.
Request:
{
"intent_id": "c3d4e5f6-...",
"include_children": true
}
Returns reversibility status, constraints, time elapsed, and child dependency analysis.
Policy Replay
POST /governance/replay
Replay provenance records through an alternative policy. Deterministic "what-if" analysis: "What would have happened if we'd used policy X instead?"
Request:
{
"agent_id": "your-agent-id",
"template_id": "strict_safety",
"limit": 50
}
Response:
{
"total_replayed": 50,
"replay_policy": {"max_values": {"speed": 3.0}},
"changes": {"upgraded": 5, "downgraded": 12, "unchanged": 33},
"results": [
{
"epoch": 42,
"agent_id": "your-agent-id",
"action_type": "motor_command",
"original_decision": "ALLOW",
"replayed_decision": "CLAMP",
"change": "more_restrictive"
}
]
}
Use for policy regression testing before deploying new policies, or forensic investigation.
Counterfactual Analysis
POST /governance/counterfactual
Simulate an action against multiple policies simultaneously. Returns a decision matrix showing how each policy handles the same action.
Request:
{
"action_payload": {"endpoint": "/deploy", "replicas": 10},
"action_type": "api_call",
"policies": [
{"label": "conservative", "template_id": "strict_safety"},
{"label": "permissive", "policy_context": {"max_values": {"replicas": 20}}},
{"label": "deny-all", "policy_context": {"forbidden_keys": ["replicas"]}}
],
"include_historical": true,
"agent_id": "your-agent-id"
}
Response includes consensus analysis (do all policies agree?), decision distribution, and optional historical comparison.
Intent Navigation
GET /governance/intents/{intent_id}/children
Return all direct child intents of a parent intent. Audit multi-agent delegation hierarchies.
GET /governance/intents/{intent_id}/ancestry
Walk up the intent hierarchy from leaf to root. Full authorization chain for auditing.
GET /governance/intents/{intent_id}/tree
Return the full delegation tree rooted at an intent. Accepts optional max_depth query parameter (default 10).
Policy Templates
GET /governance/policy-templates — free, no API key required
List available named policy templates. Use template IDs with verify, replay, and counterfactual endpoints instead of inline policy definitions.
Export
POST /governance/export/csv — export provenance records as CSV.
POST /governance/export/sarif — export provenance in SARIF format (Static Analysis Results Interchange Format) for security tooling integration.
POST /governance/export/merkle — export provenance as a Merkle tree with root hash and leaf hashes for independent integrity verification.
All export endpoints accept optional agent_id, time_range_start, time_range_end, and limit parameters.
Health and Audit
GET /governance/health-score — overall gateway health score including agent count, healthy agent count, and chain integrity rate.
GET /governance/audit-summary — aggregate statistics across all provenance: total records, total agents, decision distribution, and chain integrity status.
GET /governance/agent-compliance/{agent_id} — compliance profile for a specific agent: compliance score, chain integrity, total decisions, and outcome success rate.
Media Attestation
POST /media/attest — $0.05 per call
Attest media files (photos, videos, audio, documents) with SHA-256 hashing and provenance chain inclusion.
Request:
{
"agent_id": "your-agent-id",
"media_hash": "a1b2c3d4e5f6...64-char-hex-sha256",
"media_type": "PHOTO",
"media_size_bytes": 2048576,
"capture_timestamp_utc": "2026-02-26T12:00:00Z",
"description": "Generated report screenshot"
}
Required fields: agent_id, media_hash (64-char hex SHA-256), media_type (PHOTO | VIDEO | AUDIO | DOCUMENT), media_size_bytes, capture_timestamp_utc.
Optional fields: description, tags, capture_location (lat/lng), device_info, frame_hashes (for video).
Response:
{
"attestation_id": "e5f6a7b8-...",
"certificate_id": "mca_abc123",
"media_hash": "a1b2c3d4e5f6...",
"media_type": "PHOTO",
"epoch": 45,
"hash_prev": "...",
"hash_curr": "b8c9d0e1...",
"verification_url": "https://governance.taskhawktech.com/media/verify/mca_abc123",
"chain_length": 45,
"timestamp_utc": "2026-02-26T12:00:05Z"
}
Media Verify
POST /media/verify — free, no API key required
Verify that media content matches a specific attestation certificate.
Request:
{
"media_hash": "a1b2c3d4e5f6...64-char-hex-sha256",
"certificate_id": "mca_abc123"
}
Response:
{
"verified": true,
"certificate_id": "mca_abc123",
"media_hash_match": true,
"chain_integrity": true,
"pqc_signature_valid": true,
"reason": "Media hash matches certificate, chain intact"
}
Media Verify Lookup
GET /media/verify/{certificate_id} — free, no API key required
Look up a specific media attestation by its certificate ID. Returns the full attestation record including attesting agent, epoch, and chain integrity.
Passport
All Passport endpoints are free and require no authentication.
GET /passport/{agent_id}
Returns an agent's trust passport including score, tier, badges, and activity stats.
{
"agent_id": "your-agent-id",
"trust_score": 0.95,
"tier": "gold",
"badges": ["verified", "consistent", "high_volume"],
"stats": {
"total_decisions": 1250,
"attestations": 890,
"bindings": 340,
"outcomes_achieved": 310,
"chain_intact": true,
"active_days": 45,
"current_streak": 12
}
}
GET /passport/{agent_id}/badge.svg
Returns an embeddable SVG trust badge. Use in agent descriptions, documentation, or dashboards.
GET /passport/{agent_id}/history
Returns full decision history for an agent.
GET /passport/leaderboard
Returns top trusted agents by trust score. Accepts optional limit query parameter (1-200, default 50).
Response:
{
"agents": [
{ "agent_id": "top-agent", "trust_score": 0.98, "tier": "gold" }
],
"total": 150
}
POST /passport/{agent_id}/claim — requires API key
Link an agent's passport to your operator account. Must provide X-API-Key header.
Response:
{
"agent_id": "your-agent-id",
"claimed": true,
"profile": { "...passport profile..." }
}
Returns 409 if already claimed by another operator, 404 if no passport exists yet.
Agent Discovery
GET /.well-known/agent.json
Returns the A2A protocol agent card. No authentication required.
curl https://governance.taskhawktech.com/.well-known/agent.json
Returns capabilities, supported skills, SDK references, and free-tier signup details.
MCP
For MCP-native agents, connect directly via streamable-http transport:
https://governance.taskhawktech.com/mcp/
360 tools, 2 resources, 2 prompts. Auto-provisions a free-tier key on first tool call if no API key is provided.
Python SDK
pip install kevros
# or
uv pip install kevros
from kevros_governance import GovernanceClient
client = GovernanceClient(agent_id="your-agent-id")
result = client.verify(
action_type="api_call",
action_payload={"endpoint": "/deploy"},
agent_id="your-agent-id",
)
print(result.decision) # ALLOW, CLAMP, or DENY
Enforcement Modes
Every operator key has an enforcement mode that controls how decisions are applied:
- enforce (default) — fail-closed. DENY means DENY. Release tokens are only issued for ALLOW/CLAMP.
- advisory — shadow mode. DENY decisions are logged but overridden to ALLOW. No release token is issued for would-be denials. Use for testing policies before enforcing them.
- gated — human-in-the-loop. DENY decisions are held for operator approval. Poll
/governance/gated/{request_id} for status.
- deny — kill-switch. ALL requests are blocked regardless of policy evaluation. Use for emergency shutdown.
The enforcement_mode field is returned in every verify response. Use /enforcement to check your current mode.
Enforcement mode changes require admin-level access and are not available through the plugin. Contact your administrator or use the admin API directly.
Decision Approach
When collaborating with another agent:
- Check their passport first —
GET /passport/{agent_id} returns trust score, tier, and history
- Embed badges — Use
GET /passport/{agent_id}/badge.svg in your agent's description to show your trust level
- Trust thresholds:
- Gold tier (score >= 90%) — proceed with normal collaboration
- Silver tier (score 50-89%) — verify their actions before relying on results
- Bronze tier (score < 50%) — require bound intents with outcome verification
- No history — start with small, low-risk interactions and build trust incrementally
- Verify before you rely — Use
/governance/verify-token to independently confirm any release token a peer shares with you
Pricing
Subscriptions:
- Free tier: 1,000 calls/month, instant signup, no payment required
- Scout: $29/mo — 5,000 calls
- Sentinel: $149/mo — 50,000 calls
- Sovereign: $499/mo — 500,000 calls
Per-call (via x402 USDC, no subscription required):
- Verify: $0.01
- Attest: $0.02
- Bind: $0.02
- Media Attest: $0.05
- Compliance Bundle: $0.05
- Batch: each sub-operation metered individually
- Verify Outcome: free with Bind
- Delegation, Replay, Counterfactual, Export, Health, Audit: metered per call
- Passport, Media Verify, Reputation, Verify Token, Policy Templates: free
Subscription calls are metered against your monthly allowance. x402 per-call pricing applies when paying per-call without a subscription.
Upgrade at https://www.taskhawktech.com/pricing
