Risk API - Mnemom Docs

The Risk API provides seven 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

Full reference ↗ Compute a context-aware risk assessment for an individual agent. Requires the risk_assessment feature flag on the caller’s plan. 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 — also scales the composite score for larger amounts (see Amount scaling)
`context.counterparty_id`	string	No	Counterparty agent or entity
`context.use_case`	string	No	Free-text description of the use case
`source`	string	No	`api` (default) or `playground`

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, pending, proving, verified, or failed — see proof lifecycle), and created_at. Results are cached 5 minutes per {agent_id, action_type, risk_tolerance, amount} tuple.

Assess team risk

POST /v1/risk/assess/team

Full reference ↗ 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[]	One of `agent_ids` / `team_id`	Explicit agent roster
`team_id`	string	One of `agent_ids` / `team_id`	Resolve the roster from this team instead
`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	Free-text coordination mode (e.g. `sequential`)

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}

Full reference ↗ Retrieve a previously computed individual risk assessment by ID (ra-...). Requires an active risk_assessment entitlement (403 feature_gated otherwise); an assessment owned by another account, or absent, returns 404.

Get team assessment

GET /v1/risk/team-assessments/{assessment_id}

Full reference ↗ Retrieve a previously computed team risk assessment by ID (tra-...). Requires an active team_risk_assessment entitlement; a team assessment owned by another account, or absent, returns 404 — see Authorization model.

Get risk history

GET /v1/risk/history/{agent_id}

Full reference ↗ Retrieve risk assessment history for an agent, most recent first, scoped to the caller’s account. Query parameters:

Parameter	Type	Default	Description
`limit`	number	20	1—100
`offset`	number	0	Number of assessments to skip
`include_playground`	boolean	false	Include playground/test-run assessments alongside production ones

Response: { assessments: RiskAssessment[], total, limit, offset }

Get team risk history

GET /v1/risk/team-history/{team_id}

Full reference ↗ Retrieve team risk assessment history for a team, most recent first, scoped to the caller’s account. Same limit (default 20) / offset query parameters as individual history. Response: { team_id, assessments: TeamRiskAssessment[], total, limit, offset }

Get proof

GET /v1/risk/proofs/{proof_id}

Full reference ↗ Retrieve a ZK proof record (rpf-...) by id, generated fire-and-forget after /risk/assess or /risk/assess/team. Requires the entitlement for the assessment type the proof verifies; a proof owned by another account, or absent, returns 404. Response fields:

Field	Type	Description
`proof_id`	string	Proof identifier
`proof_type`	string	`individual_risk` or `team_coherence`
`assessment_id`	string	The linked risk (or team risk) assessment
`status`	string	`pending`, `proving`, `verified`, or `failed`
`image_id`	string \| null	Proving-guest image identifier, once known
`verified`	boolean \| null	Whether the proof independently verified
`proving_duration_ms`	number \| null	How long proving took, once complete
`retry_count`	number	Number of proving retries so far
`error_message`	string \| null	Present when `status` is `failed`
`created_at` / `updated_at`	string	Timestamps

Feature gating

Individual assessment creation (POST /v1/risk/assess) requires the risk_assessment feature flag on the caller’s plan (402 if the plan lacks it). Reading a stored resource — an assessment, a team assessment, history, or a proof — additionally requires an active risk_assessment or team_risk_assessment entitlement depending on resource type; authenticated-but-not-entitled returns 403 feature_gated. See Pricing for current μ-based rates and what’s included.

Error codes

Code	Meaning
400	Invalid request body (missing required fields, invalid action type, etc.)
401	Missing or invalid authentication (anonymous or invalid token)
402	Plan lacks the `risk_assessment` feature (on assessment creation)
403	Authenticated but not entitled to read this resource type (`feature_gated`)
404	Resource not found, or owned by a different account
429	Rate limit exceeded
503	The account/binding needed to scope this read could not be resolved
500	Internal server error

​Endpoints

​Assess individual risk

​Assess team risk

​Get assessment

​Get team assessment

​Get risk history

​Get team risk history

​Get proof

​Feature gating

​Error codes

​See also