Mnemom Risk API

Risk assessment endpoints.

GitHub OpenAPI

Operations 7

POST /risk/assess Assess risk for a single agent action #
POST /risk/assess/team Assess risk for a team of agents #
GET /risk/assessments/{assessment_id} Get a single risk assessment by id #
GET /risk/history/{agent_id} List historical risk assessments for an agent #
GET /risk/proofs/{proof_id} Get a ZK proof for a risk assessment #
GET /risk/team-assessments/{assessment_id} Get a single team risk assessment by id #
GET /risk/team-history/{team_id} List historical team risk assessments for a team #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/mnemom-ai:mnemom-ai-risk-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

mnemom-ai-risk-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Mnemom Risk API
  description: Trust infrastructure for AI agents. Transparent alignment verification, behavioral drift detection, and accountability primitives.
  version: 1.0.0
  contact:
    name: Mnemom
    url: https://mnemom.ai
    email: support@mnemom.ai
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.mnemom.ai/v1
  description: Production
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Risk
  description: Risk assessment endpoints.
paths:
  /risk/assess:
    post:
      operationId: assessRisk
      x-proxied: RISK_SERVICE
      summary: Assess risk for a single agent action
      description: Compute an individual risk assessment for an agent about to take an action. Requires JWT auth and the `risk_assessment` feature flag on the caller's plan. Dispatches a ZK proof request asynchronously (best-effort; check `/risk/proofs/{proof_id}` to retrieve). Cached for 5 minutes per `{agent_id, action_type, risk_tolerance, amount}` tuple. An agent whose reputation is private can be assessed only by a member of its governing org (403 `reputation_private` otherwise); a tombstoned agent returns 404.
      tags:
      - Risk
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              - context
              properties:
                agent_id:
                  type: string
                source:
                  type: string
                  enum:
                  - api
                  - playground
                  default: api
                context:
                  type: object
                  required:
                  - action_type
                  properties:
                    action_type:
                      type: string
                      enum:
                      - financial_transaction
                      - data_access
                      - task_delegation
                      - tool_invocation
                      - autonomous_operation
                      - multi_agent_coordination
                    amount:
                      type: number
                    counterparty_id:
                      type: string
                    use_case:
                      type: string
                    risk_tolerance:
                      type: string
                      enum:
                      - conservative
                      - moderate
                      - aggressive
                      default: moderate
      responses:
        '200':
          description: Risk assessment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskAssessment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /risk/assess/team:
    post:
      operationId: assessTeamRisk
      x-proxied: RISK_SERVICE
      summary: Assess risk for a team of agents
      description: 'Compute a team-level risk assessment given an explicit `agent_ids` list (or a `team_id` to resolve the roster). Produces three-pillar results: portfolio, coherence, concentration, plus weakest-link and Shapley attribution. Dispatches a team-coherence ZK proof asynchronously. Every agent whose reputation is private can be assessed only by a member of its governing org (403 `reputation_private` otherwise); a tombstoned agent returns 404.'
      tags:
      - Risk
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - context
              properties:
                agent_ids:
                  type: array
                  items:
                    type: string
                  description: Explicit agent roster; required if `team_id` is not provided.
                team_id:
                  type: string
                  description: Resolve roster from this team id; required if `agent_ids` is not provided.
                source:
                  type: string
                  enum:
                  - api
                  - playground
                context:
                  type: object
                  required:
                  - action_type
                  properties:
                    action_type:
                      type: string
                    amount:
                      type: number
                    use_case:
                      type: string
                    risk_tolerance:
                      type: string
                    team_task:
                      type: string
                    coordination_mode:
                      type: string
                    trigger:
                      type: string
                    governance_median:
                      type:
                      - number
                      - 'null'
                    conflict_edge_count:
                      type: integer
                    conscience_universal:
                      type:
                      - boolean
                      - 'null'
      responses:
        '200':
          description: Team risk assessment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamRiskAssessment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /risk/assessments/{assessment_id}:
    get:
      operationId: getRiskAssessment
      x-proxied: RISK_SERVICE
      summary: Get a single risk assessment by id
      description: 'Authorization: JWT required; the risk service resolves the caller''s billing account from the token (never from the path) and scopes the query to it, so an assessment owned by another account (or absent) returns 404 and never another tenant''s data.'
      tags:
      - Risk
      security:
      - BearerAuth: []
      parameters:
      - name: assessment_id
        in: path
        required: true
        schema:
          type: string
        description: Individual assessment id (`ra-…`).
      responses:
        '200':
          description: Assessment row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskAssessment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /risk/history/{agent_id}:
    get:
      operationId: getRiskHistory
      x-proxied: RISK_SERVICE
      summary: List historical risk assessments for an agent
      description: 'Authorization: JWT required; the risk service resolves the caller''s billing account from the token (never from the path) and filters the history by both the agent id and that account, so an agent owned by another account returns an empty page and never another tenant''s data.'
      tags:
      - Risk
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: limit
        in: query
        required: false
        description: Maximum number of risk assessments to return (most recent first). 1–100, default 20.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: offset
        in: query
        required: false
        description: Number of assessments to skip before returning results, for pagination. Default 0.
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: include_playground
        in: query
        required: false
        description: When true, include assessments produced in playground/test runs alongside production ones. Default false (production only).
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: History page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  assessments:
                    type: array
                    items:
                      $ref: '#/components/schemas/RiskAssessment'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /risk/proofs/{proof_id}:
    get:
      operationId: getRiskProof
      x-proxied: RISK_SERVICE
      summary: Get a ZK proof for a risk assessment
      description: 'Retrieve a ZK proof artifact (individual or team-coherence) by its proof id. Proofs are generated fire-and-forget after `/risk/assess` and `/risk/assess/team` and may take tens of seconds to complete. Authorization: JWT required; the proof is returned only after the risk service re-verifies that the assessment it proves belongs to the caller''s billing account (resolved from the token, never the path), so a proof owned by another account (or absent) returns 404 and never another tenant''s data.'
      tags:
      - Risk
      security:
      - BearerAuth: []
      parameters:
      - name: proof_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Proof row (status, artifact, metadata).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /risk/team-assessments/{assessment_id}:
    get:
      operationId: getTeamRiskAssessment
      x-proxied: RISK_SERVICE
      summary: Get a single team risk assessment by id
      description: 'Authorization: JWT required; the risk service resolves the caller''s billing account from the token (never from the path) and scopes the query to it, so a team assessment owned by another account (or absent) returns 404 and never another tenant''s data.'
      tags:
      - Risk
      security:
      - BearerAuth: []
      parameters:
      - name: assessment_id
        in: path
        required: true
        schema:
          type: string
        description: Team assessment id (`tra-…`).
      responses:
        '200':
          description: Team assessment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamRiskAssessment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /risk/team-history/{team_id}:
    get:
      operationId: getTeamRiskHistory
      x-proxied: RISK_SERVICE
      summary: List historical team risk assessments for a team
      tags:
      - Risk
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TeamId'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: History page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  team_id:
                    type: string
                  assessments:
                    type: array
                    items:
                      $ref: '#/components/schemas/TeamRiskAssessment'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: Paid feature gate — the caller's plan doesn't include this operation's feature flag. Emitted by `requireFeature` / `requireEntitlement` in `src/org/rbac.ts`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: An upstream dependency is currently unavailable. The request was not processed; retry after the cooldown window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
        X-RateLimit-Limit:
          description: Requests permitted per window.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests remaining in the current window (0 on a 429).
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Reset:
          description: Unix epoch seconds at which the current window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    TeamRiskAssessment:
      type: object
      description: Team risk assessment row (`tra-…`). Produced by `POST /risk/assess/team`. Three-pillar result (portfolio + coherence + concentration) with weakest-link and Shapley attribution per member.
      properties:
        assessment_id:
          type: string
        team_id:
          type:
          - string
          - 'null'
        agent_count:
          type: integer
        team_risk_score:
          type: number
        team_risk_level:
          type: string
        team_coherence_score:
          type: number
        team_recommendation:
          type: string
        portfolio_risk:
          type: object
          additionalProperties: true
        coherence_risk:
          type: object
          additionalProperties: true
        concentration_risk:
          type: object
          additionalProperties: true
        weakest_link_risk:
          type: object
          additionalProperties: true
        individual_assessments:
          type: array
          items:
            $ref: '#/components/schemas/RiskAssessment'
        outliers:
          type: array
        clusters:
          type: array
        value_divergences:
          type: array
        shapley_values:
          type: object
          additionalProperties:
            type: number
        synergy_type:
          type: string
        explanation:
          type: string
        proof_id:
          type:
          - string
          - 'null'
        proof_status:
          type: string
        created_at:
          type: string
          format: date-time
      additionalProperties: true
    RiskAssessment:
      type: object
      description: Individual risk assessment row (`ra-…`). Produced by `POST /risk/assess`.
      properties:
        assessment_id:
          type: string
        agent_id:
          type: string
        risk_score:
          type: number
          description: 0–1000 integer (higher = riskier).
        risk_level:
          type: string
          enum:
          - low
          - moderate
          - high
          - critical
        recommendation:
          type: string
          enum:
          - proceed
          - proceed_with_caveats
          - require_approval
          - block
        confidence:
          type: string
          enum:
          - insufficient
          - low
          - medium
          - high
        contributing_factors:
          type: array
          items:
            type: object
            additionalProperties: true
        suggested_thresholds:
          type: object
          additionalProperties: true
        explanation:
          type: string
        proof_id:
          type:
          - string
          - 'null'
        proof_status:
          type: string
          enum:
          - none
          - pending
          - completed
          - failed
        created_at:
          type: string
          format: date-time
      additionalProperties: true
    Error:
      type: object
      description: Canonical error envelope (ADR-API-001 conv 1). `error` is always an object — never a bare string. Every 4xx/5xx response across the API conforms to this shape; the runtime helper is `src/http-errors.ts::buildErrorBody`.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              pattern: ^[a-z][a-z0-9_]*$
              description: 'Stable, machine-matchable failure identifier (lowercase snake_case). Clients may branch on this; the string is part of the contract.


                **Status-class defaults** — emitted when no caller code is supplied (`errorCodeForStatus(status)`): `bad_request` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `conflict` (409), `gone` (410), `precondition_failed` (412), `payload_too_large` (413), `unsupported_media_type` (415), `unprocessable_entity` (422), `precondition_required` (428), `rate_limited` (429), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). Fallback `error` for unmapped statuses.


                **Caller-supplied codes** — handlers may pass an explicit `code` for a specific failure class. Examples: `agent_not_found`, `invalid_hash_proof`, `already_linked`, `idempotency_conflict`, `feature_gated`, `schema_validation_failed`, `no_token`, `bad_canonical_payload`.


                **Care-framed sub-resource codes** — the cards-as-primitive surface passes its stable care code-string straight through as `error.code`. Examples: `if_match_absent`, `if_match_stale`, `if_match_malformed`, `primitive_validation_failed`.'
            message:
              type: string
              description: Human-readable, care-framed explanation of the failure.
            details:
              description: 'Optional structured context for the failure (any JSON value: object, array, or primitive). Common shapes: validation findings list, idempotency-conflict diff, `{presented_etag, current_etag}` on a stale `If-Match`, etc. Mirrors the helper''s `details?: unknown`.'
  parameters:
    AgentId:
      name: agent_id
      in: path
      required: true
      schema:
        type: string
      description: Agent identifier (e.g. smolt-abc123)
    TeamId:
      name: team_id
      in: path
      required: true
      schema:
        type: string
      description: Team identifier (UUID)
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase JWT token in Authorization: Bearer header'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Mnemom-Api-Key
      description: Mnemom API key (mnm_... format)
    ServiceRole:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase service role bearer JWT. Used by /blog admin operations that talk directly to Supabase. NOT used by /internal/* or /v1/arena/internal/* — those use the custom-header schemes below.
    InternalKeyAuth:
      type: apiKey
      in: header
      name: X-Internal-Key
      description: Internal service-to-service shared secret, timing-safe compared against INTERNAL_API_KEY. Used by /internal/* gateway routes (compose, agents, webhooks emit).
    ServiceKeyAuth:
      type: apiKey
      in: header
      name: X-Service-Key
      description: Service-to-service shared secret, timing-safe compared against MNEMOM_SERVICE_KEY. Used by /v1/arena/internal/*, /v1/on-chain/*, and the /v1/internal/* readers consumed by the reputation cron.
    CoherenceTokenAuth:
      type: http
      scheme: bearer
      description: Per-cell coherence bearer token. Provisioned in 1Password vault `mnemom-coherence` (one item per receiver). Value compared against COHERENCE_<NAME>_SERVICE_TOKEN_EXPECTED. Used by /v1/internal/coherence/* and /v1/internal/governance/dispatch.
    ArenaCandidateTokenAuth:
      type: http
      scheme: bearer
      description: Dedicated arena writer token (ADR-004 §"Arena dedicated writer token"). Compared against ARENA_RECIPE_CANDIDATE_TOKEN. The token's only capability is writing recipe candidates with writer_identity='arena-bypass' (stamped server-side). Used by POST /v1/internal/recipe-candidates.
    CustomerVoiceTokenAuth:
      type: http
      scheme: bearer
      description: Customer Voice API bearer token. Timing-safe compared against CUSTOMER_VOICE_API_TOKEN. Grants access to all /v1/internal/feedback/* endpoints (MNE-1876). No customer-facing or reporter-read capability.
    CookieAuth:
      type: apiKey
      in: cookie
      name: mnemom_session
      description: 'HttpOnly, Secure, SameSite=Lax cookie issued by /v1/auth/sign-in (or the SSO / email-callback flows). The value is an AES-256-GCM-encrypted blob of {access_token, refresh_token, issued_at, auth_method}. Browser clients include this automatically with `credentials: "include"`.'
    LicenseJwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: License JWT (HS256, HMAC-signed with LICENSE_SIGNING_SECRET). Used by self-hosted deployment instances to authenticate `/v1/deployments/heartbeat`. Not interchangeable with the Supabase user JWT.
    AgentAuth:
      type: apiKey
      in: header
      name: X-Mnemom-Agent-Proof
      description: 'Agent possession proof: the full SHA-256 hex digest of `${apiKey}|${agentName}` (or `${apiKey}` for an unnamed singleton agent) — the same `hash_proof` primitive used by POST /v1/agents claim, link-agent, and verify-binding. The server resolves the agent by `agent_hash = proof[:16]`. The agent''s *own* identity (ADR-API-001 third auth class) — distinct from ApiKeyAuth (`X-Mnemom-Api-Key`, which resolves a user/account, not an agent).'