> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanos.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Risk Score

> Score one agent from its signed event chain: identity strength, compliance behaviour and exposure, combined as exposure × (1 − trust), 0..100, with the factors that made each component.  
A derived judgement over the chain — never an input to any verification. Anyone holding the chain recomputes the same number.  
Use your own organization DID in `orgDid` to score your agents (evidence URNs included). Use a partner organization's DID to score theirs; this requires an active sharing grant, and the evidence URNs are withheld.  
The `posture` block is the read-out of the facts before any weighting; `remediations` say what would lower the score and point at the evidence.



## OpenAPI

````yaml /versions/2026-10-16.yaml get /intelligence/risk
openapi: 3.1.0
info:
  title: Humanos API
  description: Humanos API
  version: '1.0'
  contact: {}
servers:
  - url: https://api.humanos.tech
security: []
tags:
  - name: humanosApp
    description: ''
paths:
  /intelligence/risk:
    get:
      tags:
        - Intelligence
      summary: Get Risk Score
      description: >-
        Score one agent from its signed event chain: identity strength,
        compliance behaviour and exposure, combined as exposure × (1 − trust),
        0..100, with the factors that made each component.  

        A derived judgement over the chain — never an input to any verification.
        Anyone holding the chain recomputes the same number.  

        Use your own organization DID in `orgDid` to score your agents (evidence
        URNs included). Use a partner organization's DID to score theirs; this
        requires an active sharing grant, and the evidence URNs are withheld.  

        The `posture` block is the read-out of the facts before any weighting;
        `remediations` say what would lower the score and point at the evidence.
      operationId: intelligence_risk
      parameters:
        - name: orgDid
          required: true
          in: query
          description: >-
            DID of the organization whose data is consulted. Your own
            organization DID needs no grant; any other requires an active
            sharing grant from that organization to yours.
          schema:
            example: did:web:org-a.example
            type: string
        - name: did
          required: true
          in: query
          description: DID of the agent to score.
          schema:
            example: did:web:humanos.tech:agent:RRJyvYvj0T-ZRBU-
            type: string
        - name: days
          required: false
          in: query
          description: Behaviour window in days, ending now. Default 30, at most 366.
          schema:
            example: 30
            type: string
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: >-
            Returns the stored risk score: the report, when it was computed and
            why, and the live variant when the inline loop has seen a call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntelligenceStoredRiskEntity'
        '400':
          description: 'Invalid query parameters: `orgDid` or `did` missing.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 400
                  message:
                    type: string
                    example: did must be a string
                  error:
                    type: string
                    example: Bad Request
        '404':
          description: >-
            sharing_not_enabled: the organization does not exist or does not
            share with you; or that organization operates no such agent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 404
                  message:
                    type: string
                    example: >-
                      sharing_not_enabled: the organization does not share with
                      you
                  error:
                    type: string
                    example: Not Found
components:
  parameters:
    ApiVersion:
      name: API-Version
      in: header
      required: false
      schema:
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
        example: '2026-10-16'
      description: >-
        Pin request, response, and webhook shapes to a specific dated API
        version (YYYY-MM-DD). Omit to use the version pinned to your API key
        (set when the key is created; new keys default to the latest version).
        New integrations should target the latest version.
  schemas:
    IntelligenceStoredRiskEntity:
      type: object
      properties:
        report:
          description: The risk report.
          allOf:
            - $ref: '#/components/schemas/IntelligenceRiskEntity'
        computedAt:
          type: string
          description: When the stored score was last recomputed from the chain.
          example: '2026-09-09T11:30:00.000Z'
        trigger:
          type: string
          description: 'What caused the recompute: a chain event type, `read`, or `manual`.'
          example: VERIFICATION_DENIED
        previousScore:
          type:
            - number
            - 'null'
          description: The score before this recompute; null on the first.
          example: 28
        live:
          description: Absent until the inline loop has seen a call.
          allOf:
            - $ref: '#/components/schemas/RiskLiveEntity'
      required:
        - report
        - computedAt
        - trigger
        - previousScore
    IntelligenceRiskEntity:
      type: object
      properties:
        did:
          type: string
          description: DID of the agent scored.
          example: did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35
        computedAt:
          type: string
          description: When the score was computed.
          example: '2026-09-09T11:30:00.000Z'
        basis:
          type: string
          description: '`chain`: signed facts only.'
          example: chain
        window:
          type: object
          description: 'The period the score reads: `from` to `to`, `days` long.'
          example:
            from: '2026-08-10T11:30:00.000Z'
            to: '2026-09-09T11:30:00.000Z'
            days: 30
        score:
          type: number
          description: 0..100 — exposure × (1 − trust) × anomaly.
          example: 31
        trust:
          type: number
          description: mean(identity, compliance), 0..1
          example: 0.625
        components:
          description: >-
            The components the score combines, each with the factors that made
            it.
          allOf:
            - $ref: '#/components/schemas/RiskComponentsEntity'
        posture:
          description: The facts read off the chain, before any weighting.
          allOf:
            - $ref: '#/components/schemas/RiskPostureEntity'
        remediations:
          description: What would lower the score, the largest first.
          type: array
          items:
            $ref: '#/components/schemas/RiskRemediationEntity'
      required:
        - did
        - computedAt
        - basis
        - window
        - score
        - trust
        - components
        - posture
        - remediations
    RiskLiveEntity:
      type: object
      properties:
        score:
          type: number
          description: >-
            The chain score × the latest inline anomaly multiplier, capped at
            100.
          example: 50
        anomaly:
          type: number
          description: >-
            Multiplier ≥ 1 from the last call judged against the agent's own
            past.
          example: 1.6
        state:
          type: string
          description: >-
            `live`: judged against enough history. `cold`: too little history.
            `timeout` or `unavailable`: the judgement did not run.
          enum:
            - live
            - cold
            - timeout
            - unavailable
          example: live
        at:
          type: string
          description: When the last call was judged.
          example: '2026-09-09T03:12:00.000Z'
      required:
        - score
        - anomaly
        - state
        - at
    RiskComponentsEntity:
      type: object
      properties:
        identity:
          description: >-
            How strongly the agent's identity is established: its keys' rung,
            its bootstrap anchor, its affiliation, its key's age.
          allOf:
            - $ref: '#/components/schemas/RiskComponentEntity'
        compliance:
          description: >-
            How the agent behaves under its mandates: denies, unreported
            outcomes, step-ups, proof failures, attempts after a revocation.
          allOf:
            - $ref: '#/components/schemas/RiskComponentEntity'
        exposure:
          description: >-
            How much authority the agent holds: its active mandates, and those
            with neither a cap nor an expiry.
          allOf:
            - $ref: '#/components/schemas/RiskComponentEntity'
        anomaly:
          description: The multiplier for behaviour unlike the agent's own past.
          allOf:
            - $ref: '#/components/schemas/RiskAnomalyEntity'
      required:
        - identity
        - compliance
        - exposure
        - anomaly
    RiskPostureEntity:
      type: object
      properties:
        rung:
          type: string
          description: The agent's rung, as `<assurance>/<binding>`.
          example: pop/custodial
        bootstrapAnchor:
          type: string
          description: What vouched for the agent at registration.
          example: manual
        affiliated:
          type: boolean
          description: An organization operates the agent, by a signed affiliation.
          example: true
        keyAgeDays:
          type:
            - number
            - 'null'
          description: Whole days since the agent's key was minted; null when unknown.
          example: 2
        activeMandates:
          type: number
          description: Active mandates that name the agent.
          example: 7
        unboundedAuthorizations:
          type: number
          description: Active plain authorizations with neither a cap nor an expiry.
          example: 2
        verifications:
          type: number
          description: Verifications of the agent in the window.
          example: 17
        approvals:
          type: number
          description: Verifications that allowed the call.
          example: 10
        denies:
          type: number
          description: Verifications that denied the call.
          example: 7
        denyRatio:
          type:
            - number
            - 'null'
          description: >-
            Denies over verifications, to three decimals; null with no
            verification.
          example: 0.412
        distinctFailedRules:
          description: The rules that failed in a denied verification, each once.
          example:
            - review_required
          type: array
          items:
            type: string
        unreportedOutcomes:
          type: number
          description: >-
            Allowed calls with no ACTION_COMPLETED or ACTION_FAILED reported
            after them.
          example: 5
        stepUps:
          type: object
          description: >-
            Step-ups the person was asked for: approved, declined, and expired
            unanswered.
          example:
            approved: 4
            declined: 0
            expired: 2
        proofFailures:
          type: number
          description: >-
            Verifications refused because the agent's proof of possession
            failed.
          example: 0
        postRevocationAttempts:
          type: number
          description: Verifications presented after the mandate was revoked.
          example: 0
      required:
        - rung
        - bootstrapAnchor
        - affiliated
        - keyAgeDays
        - activeMandates
        - unboundedAuthorizations
        - verifications
        - approvals
        - denies
        - denyRatio
        - distinctFailedRules
        - unreportedOutcomes
        - stepUps
        - proofFailures
        - postRevocationAttempts
    RiskRemediationEntity:
      type: object
      properties:
        summary:
          type: string
          description: What would lower the score, in words.
          example: >-
            Put an expiry and a use cap on 2 open-ended authorization(s) — the
            largest line in the score
        evidence:
          description: The URNs it points at. Empty across organizations.
          example:
            - urn:via:credential:550e8400-e29b-41d4-a716-446655440000
          type: array
          items:
            type: string
      required:
        - summary
        - evidence
    RiskComponentEntity:
      type: object
      properties:
        value:
          type: number
          description: The component, 0..1.
          example: 0.65
        factors:
          description: >-
            The factors that made the component, each with its signed
            contribution.
          type: array
          items:
            $ref: '#/components/schemas/RiskFactorEntity'
      required:
        - value
        - factors
    RiskAnomalyEntity:
      type: object
      properties:
        value:
          type: number
          description: Multiplier ≥ 1. 1 until the live loop exists.
          example: 1
        state:
          type: string
          description: >-
            `cold`: too little history to judge against. `not_computed`: no
            anomaly read yet.
          enum:
            - cold
            - not_computed
          example: cold
      required:
        - value
        - state
    RiskFactorEntity:
      type: object
      properties:
        name:
          type: string
          description: The factor, as a code.
          example: unreported_outcomes
        delta:
          type: number
          description: Signed contribution to the component.
          example: -0.15
        note:
          type: string
          description: 'The factor in words: what the chain showed.'
          example: 5 of 10 approvals have no ACTION_COMPLETED / FAILED after them
        evidence:
          description: >-
            Event or mandate URNs behind the factor, at most 20. Empty across
            organizations.
          example:
            - urn:via:event:550e8400-e29b-41d4-a716-446655440000
          type: array
          items:
            type: string
      required:
        - name
        - delta
        - note
        - evidence

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.