Risk API - Mnemom Docs

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. GET endpoints that retrieve a stored resource by ID are account-scoped — a valid token from a different account returns 404 rather than 403 to avoid leaking resource existence. See Authorization model for the full specification.

Endpoints

Assess individual risk

POST /v1/risk/assess

Compute a context-aware risk assessment for an individual agent. Request body:

Field	Type	Required	Description
`agent_id`	string	Yes	The agent to assess
`context.action_type`	string	Yes	One of: `financial_transaction`, `data_access`, `task_delegation`, `tool_invocation`, `autonomous_operation`, `multi_agent_coordination`
`context.risk_tolerance`	string	No	`conservative`, `moderate` (default), or `aggressive`
`context.amount`	number	No	Transaction amount (for financial context)
`context.counterparty_id`	string	No	Counterparty agent or entity
`context.use_case`	string	No	Free-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 (none immediately after creation on the Free tier or when async proof dispatch does not complete; progresses to pending → completed or failed as the proof generates — see proof lifecycle), 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:

Field	Type	Required	Description
`agent_ids`	string[]	Yes	Array of agent IDs (minimum 2)
`context.action_type`	string	Yes	Action type for the team operation
`context.risk_tolerance`	string	No	Risk tolerance level
`context.team_task`	string	No	Description of the team’s task
`context.coordination_mode`	string	No	`parallel`, `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. Returns 404 for IDs that belong to a different account.

Get team assessment

GET /v1/risk/team-assessments/:assessment_id

Retrieve a previously computed team risk assessment by ID. Returns 404 for IDs that belong to a different account — see Authorization model.

Get risk history

GET /v1/risk/history/:agent_id

Retrieve risk assessment history for an agent, ordered by most recent first. Query parameters:

Parameter	Type	Default	Description
`limit`	number	50	Maximum number of assessments to return

Get proof

GET /v1/risk/proofs/:proof_id

Retrieve the ZK proof status and receipt for a risk assessment. Returns 404 for IDs that belong to a different account. Response includes:

Field	Type	Description
`proof_id`	string	Proof identifier
`status`	string	`pending`, `proving`, `completed`, or `failed` — tracks computation progress inside the proving cluster; see proof lifecycle for the assessment-level `proof_status`
`assessment_id`	string	The linked risk assessment
`receipt`	object	The STARK proof receipt (when completed)
`created_at`	string	When the proof was requested
`verified_at`	string	When the proof 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

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

​Endpoints

​Assess individual risk

​Assess team risk

​Get assessment

​Get team assessment

​Get risk history

​Get proof

​Feature gating

​Error codes