Skip to main content
The Risk API provides six endpoints for assessing, retrieving, and verifying risk scores for individual agents and teams. All endpoints require authentication via Bearer token or API key.

​
Endpoints

​
Assess Individual Risk

POST /v1/risk/assess
Compute a context-aware risk assessment for an individual agent. Request body:
FieldTypeRequiredDescription
agent_idstringYesThe agent to assess
context.action_typestringYesOne of: financial_transaction, data_access, task_delegation, tool_invocation, autonomous_operation, multi_agent_coordination
context.risk_tolerancestringNoconservative, moderate (default), or aggressive
context.amountnumberNoTransaction amount (for financial context)
context.counterparty_idstringNoCounterparty agent or entity
context.use_casestringNoFree-text description of the use case
Example request: 
{
  "agent_id": "agent-abc-123",
  "context": {
    "action_type": "financial_transaction",
    "risk_tolerance": "conservative",
    "amount": 50000,
    "counterparty_id": "vendor-xyz"
  }
}
Response: A RiskAssessment object with risk_score, risk_level, recommendation, confidence, contributing_factors, suggested_thresholds, explanation, proof_id, proof_status, and created_at.

​
Assess Team Risk

POST /v1/risk/assess/team
Compute a risk assessment for a team of agents, including three-pillar analysis, Shapley attribution, outlier detection, and synergy classification. Request body:
FieldTypeRequiredDescription
agent_idsstring[]YesArray of agent IDs (minimum 2)
context.action_typestringYesAction type for the team operation
context.risk_tolerancestringNoRisk tolerance level
context.team_taskstringNoDescription of the team’s task
context.coordination_modestringNoparallel, sequential, hierarchical, or consensus
Example request: 
{
  "agent_ids": ["agent-a", "agent-b", "agent-c"],
  "context": {
    "action_type": "multi_agent_coordination",
    "risk_tolerance": "moderate",
    "team_task": "customer-support-pipeline",
    "coordination_mode": "sequential"
  }
}
Response: A TeamRiskAssessment object with team_risk_score, team_risk_level, team_coherence_score, team_recommendation, pillar breakdowns (portfolio_risk, coherence_risk, concentration_risk, weakest_link_risk), shapley_values, outliers, clusters, value_divergences, synergy_type, individual_assessments, explanation, and proof fields.

​
Get Assessment

GET /v1/risk/assessments/:assessment_id
Retrieve a previously computed individual risk assessment by ID.

​
Get Team Assessment

GET /v1/risk/team-assessments/:assessment_id
Retrieve a previously computed team risk assessment by ID.

​
Get Risk History

GET /v1/risk/history/:agent_id
Retrieve risk assessment history for an agent, ordered by most recent first. Query parameters:
ParameterTypeDefaultDescription
limitnumber50Maximum number of assessments to return

​
Get Proof

GET /v1/risk/proofs/:proof_id
Retrieve the ZK proof status and receipt for a risk assessment. Response includes:
FieldTypeDescription
proof_idstringProof identifier
statusstringpending, proving, verified, or failed
assessment_idstringThe linked risk assessment
receiptobjectThe STARK proof receipt (when verified)
created_atstringWhen the proof was requested
verified_atstringWhen verification completed (if applicable)

​
Feature Gating

Risk endpoints require the risk_assessment feature to be enabled on the caller’s billing plan. Team risk requires the team_risk_assessment feature. ZK proofs require the zk_proofs feature. See Pricing for plan details.

​
Error Codes

CodeMeaning
401Missing or invalid authentication
403Feature not available on current plan
404Assessment or proof not found
422Invalid request body (missing required fields, invalid action type, etc.)
429Rate limit exceeded
500Internal server error