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

# Get analysis

> Return the persisted deterministic analysis verdict.



## OpenAPI

````yaml https://api.qa.nlbs.ai/api/openapi.json get /analyses/{analysis_uuid}
openapi: 3.1.0
info:
  description: >-
    NL Labs AI AML API. Use Bearer API keys for protected endpoints. The /live
    and /ready probes are public.
  title: NL Labs AI
  version: 0.1.0
servers:
  - url: https://api.qa.nlbs.ai/api
security:
  - ApiKeyAuth: []
tags:
  - description: Runtime health checks and source freshness endpoints.
    name: health
  - description: Canonical entity lookup endpoints used before starting analyses.
    name: entities
  - description: AML analysis creation, status, result, and debug endpoints.
    name: analyses
  - description: Regulatory report (Motor 2) creation, status, result, and debug endpoints.
    name: reports
  - description: Versioned deterministic rules catalog endpoints.
    name: rules
  - description: Versioned regulatory reference catalog endpoints.
    name: regulatory
  - description: Webhook endpoint configuration and delivery-event operations.
    name: webhooks
paths:
  /analyses/{analysis_uuid}:
    get:
      tags:
        - analyses
      summary: Get analysis
      description: Return the persisted deterministic analysis verdict.
      operationId: get_analysis
      parameters:
        - description: Analysis execution UUID.
          in: path
          name: analysis_uuid
          required: true
          schema:
            description: Analysis execution UUID.
            format: uuid
            title: Analysis Uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisResponse'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing, malformed, expired, or invalid Bearer API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The authenticated API key does not have the required scope.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Analysis was not found for the authenticated client.
        '422':
          description: >-
            Invalid request body, path parameter, query parameter, or business
            rule.
      security:
        - HTTPBearer: []
components:
  schemas:
    AnalysisResponse:
      description: >-
        Deterministic analysis verdict returned by POST and GET
        /analyses/{uuid}.
      properties:
        links:
          $ref: '#/components/schemas/AnalysisLinks'
        risk:
          anyOf:
            - $ref: '#/components/schemas/RiskLevelOutput'
            - type: 'null'
        signal_counts:
          $ref: '#/components/schemas/SignalCounts'
        subject:
          anyOf:
            - $ref: '#/components/schemas/SubjectProfile'
            - type: 'null'
        uuid:
          format: uuid
          title: Uuid
          type: string
        versions:
          anyOf:
            - $ref: '#/components/schemas/AnalysisVersions'
            - type: 'null'
      required:
        - uuid
        - signal_counts
        - links
      title: AnalysisResponse
      type: object
    ErrorResponse:
      properties:
        detail:
          description: Stable public error message.
          examples:
            - Resource not found.
          title: Detail
          type: string
      required:
        - detail
      title: ErrorResponse
      type: object
    AnalysisLinks:
      properties:
        events:
          description: Relevant events (timeline).
          title: Events
          type: string
        explanation:
          description: On-demand operational explanation (LLM).
          title: Explanation
          type: string
        graph:
          description: Graph + signal highlight index.
          title: Graph
          type: string
        self:
          description: This analysis (lean envelope).
          title: Self
          type: string
        signals:
          description: Detailed identified signals + counts.
          title: Signals
          type: string
        snapshot:
          description: Full enrichment snapshot (audit).
          title: Snapshot
          type: string
      required:
        - self
        - graph
        - signals
        - events
        - snapshot
        - explanation
      title: AnalysisLinks
      type: object
      description: >-
        Links para os sub-recursos desta análise (grafo, sinais, eventos,
        explicação, snapshot).
    RiskLevelOutput:
      description: Final risk result for the analyzed counterparty.
      properties:
        band_floors_applied:
          items:
            $ref: '#/components/schemas/BandFloorApplied'
          title: Band Floors Applied
          type: array
        diffuse_score:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Diffuse Score
        dispositive_floor:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Dispositive Floor
        escalation_reasons:
          items:
            $ref: '#/components/schemas/EscalationReason'
          title: Escalation Reasons
          type: array
        escalation_required:
          title: Escalation Required
          type: boolean
        limitations:
          items:
            type: string
          title: Limitations
          type: array
        meta_signals:
          items:
            $ref: '#/components/schemas/SignalResult'
          title: Meta Signals
          type: array
        pillar_breakdown:
          items:
            $ref: '#/components/schemas/PillarRiskBreakdown'
          title: Pillar Breakdown
          type: array
        review_recommended:
          title: Review Recommended
          type: boolean
        review_required:
          title: Review Required
          type: boolean
        risk_color:
          $ref: '#/components/schemas/RiskColor'
        risk_level:
          $ref: '#/components/schemas/RiskLevel'
        score:
          maximum: 100
          minimum: 0
          title: Score
          type: integer
      required:
        - score
        - risk_level
        - risk_color
        - diffuse_score
        - dispositive_floor
        - review_recommended
        - review_required
        - escalation_required
      title: RiskLevelOutput
      type: object
    SignalCounts:
      properties:
        by_pillar:
          additionalProperties:
            $ref: '#/components/schemas/PillarSignalCount'
          title: By Pillar
          type: object
        score_sum:
          anyOf:
            - type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Score Sum
        total:
          title: Total
          type: integer
      required:
        - total
        - score_sum
      title: SignalCounts
      type: object
      description: Contagem de sinais por pilar de risco.
    SubjectProfile:
      additionalProperties: false
      description: Presentation-ready profile of the analyzed counterparty.
      properties:
        age_range_code:
          anyOf:
            - maximum: 9
              minimum: 0
              type: integer
            - type: 'null'
          title: Age Range Code
        age_years:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          title: Age Years
        birth_country:
          anyOf:
            - type: string
            - type: 'null'
          title: Birth Country
        birth_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Birth Date
        birth_state:
          anyOf:
            - type: string
            - type: 'null'
          title: Birth State
        capital_social:
          anyOf:
            - type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
            - type: 'null'
          title: Capital Social
        citizenship:
          anyOf:
            - type: string
            - type: 'null'
          title: Citizenship
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        company_size:
          anyOf:
            - type: string
            - type: 'null'
          title: Company Size
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
        death_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Death Status
        display_name:
          minLength: 1
          title: Display Name
          type: string
        document:
          anyOf:
            - type: string
            - type: 'null'
          title: Document
        document_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Document Type
        education_level:
          anyOf:
            - $ref: '#/components/schemas/PersonEducationLevel'
            - type: 'null'
        employee_count:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          title: Employee Count
        entity_id:
          exclusiveMinimum: 0
          title: Entity Id
          type: integer
        entity_type:
          $ref: '#/components/schemas/EntityType'
        establishment_type:
          anyOf:
            - $ref: '#/components/schemas/EstablishmentType'
            - type: 'null'
        father_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Father Name
        federal_entity_responsible:
          anyOf:
            - type: string
            - type: 'null'
          title: Federal Entity Responsible
        gender:
          anyOf:
            - $ref: '#/components/schemas/PersonGender'
            - type: 'null'
        government_branch:
          anyOf:
            - $ref: '#/components/schemas/OrganizationGovernmentBranch'
            - type: 'null'
        headquarters_entity_id:
          anyOf:
            - exclusiveMinimum: 0
              type: integer
            - type: 'null'
          title: Headquarters Entity Id
        incorporation_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Incorporation Date
        is_headquarters:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Headquarters
        last_registry_update:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Registry Update
        legal_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Legal Name
        legal_nature_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Legal Nature Code
        legal_nature_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Legal Nature Description
        main_cnae_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Main Cnae Code
        main_cnae_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Main Cnae Description
        marital_status:
          anyOf:
            - $ref: '#/components/schemas/PersonMaritalStatus'
            - type: 'null'
        mei_end_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Mei End Date
        mei_option:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mei Option
        mei_start_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Mei Start Date
        mother_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Mother Name
        nationality:
          anyOf:
            - type: string
            - type: 'null'
          title: Nationality
        normalized_name:
          minLength: 1
          title: Normalized Name
          type: string
        organization_category:
          anyOf:
            - $ref: '#/components/schemas/OrganizationCategory'
            - type: 'null'
        partner_count:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          title: Partner Count
        place_of_birth:
          anyOf:
            - type: string
            - type: 'null'
          title: Place Of Birth
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
        primary_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Primary Address
        race_color:
          anyOf:
            - $ref: '#/components/schemas/PersonRaceColor'
            - type: 'null'
        registration_status_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Registration Status Reason
        registration_status_reason_code:
          anyOf:
            - type: integer
            - type: 'null'
          title: Registration Status Reason Code
        secondary_cnae_codes:
          items:
            type: string
          title: Secondary Cnae Codes
          type: array
        simples_nacional_end_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Simples Nacional End Date
        simples_nacional_option:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Simples Nacional Option
        simples_nacional_start_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Simples Nacional Start Date
        special_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Special Status
        special_status_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Special Status Date
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
        status_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Status Date
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        ubo_count:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          title: Ubo Count
        unit_status:
          anyOf:
            - $ref: '#/components/schemas/OrganizationUnitStatus'
            - type: 'null'
        unit_status_since:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Unit Status Since
        unit_type:
          anyOf:
            - $ref: '#/components/schemas/OrganizationUnitType'
            - type: 'null'
      required:
        - entity_id
        - entity_type
        - display_name
        - normalized_name
      title: SubjectProfile
      type: object
    AnalysisVersions:
      additionalProperties: false
      description: >-
        Version identifiers for the rules, workflow, scoring, and explanation.


        `snapshot_hash` is not a version per se, but is grouped here because it
        shares the same

        availability window: both become known as soon as data_enrichment
        completes, well before

        the analysis finishes. It is injected by the API layer from the
        persisted Analysis row,

        not assembled by the workflow, since it isn't part of any step's output
        content.
      properties:
        analysis_workflow_version:
          minLength: 1
          title: Analysis Workflow Version
          type: string
        operational_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Operational Model
        operational_prompt_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Operational Prompt Version
        regulatory_catalog_version:
          minLength: 1
          title: Regulatory Catalog Version
          type: string
        rules_version:
          minLength: 1
          title: Rules Version
          type: string
        scoring_engine_version:
          minLength: 1
          title: Scoring Engine Version
          type: string
        snapshot_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Snapshot Hash
      required:
        - rules_version
        - regulatory_catalog_version
        - analysis_workflow_version
        - scoring_engine_version
      title: AnalysisVersions
      type: object
    BandFloorApplied:
      description: A signal or meta-rule that imposed a minimum risk band.
      properties:
        band_floor:
          $ref: '#/components/schemas/RiskLevel'
        floor_score:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Floor Score
        reason:
          title: Reason
          type: string
        source_code:
          title: Source Code
          type: string
        source_type:
          $ref: '#/components/schemas/BandFloorSourceType'
      required:
        - source_type
        - source_code
        - band_floor
        - floor_score
        - reason
      title: BandFloorApplied
      type: object
    EscalationReason:
      enum:
        - score_above_threshold
        - band_floor_critical
        - band_floor_high
        - diffuse_accumulation
        - thin_file_sensitive_coexistence
        - mlro_review_required
      title: EscalationReason
      type: string
    SignalResult:
      description: >-
        Auditable output of a full signal check, including signal-level
        modifiers.
      properties:
        adjusted_score:
          anyOf:
            - type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Adjusted Score
        applied_aggravants:
          items:
            $ref: '#/components/schemas/AppliedModifier'
          title: Applied Aggravants
          type: array
        applied_attenuants:
          items:
            $ref: '#/components/schemas/AppliedModifier'
          title: Applied Attenuants
          type: array
        assessed_entity_id:
          exclusiveMinimum: 0
          title: Assessed Entity Id
          type: integer
        band_floor:
          anyOf:
            - $ref: '#/components/schemas/RiskLevel'
            - type: 'null'
        base_score:
          anyOf:
            - type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Base Score
        code:
          title: Code
          type: string
        evidences:
          items:
            $ref: '#/components/schemas/Evidence'
          title: Evidences
          type: array
        graph_paths:
          items: {}
          title: Graph Paths
          type: array
        identified:
          title: Identified
          type: boolean
        kind:
          $ref: '#/components/schemas/SignalKind'
          default: observable
        limitations:
          items:
            $ref: '#/components/schemas/DataRequirement'
          title: Limitations
          type: array
        name:
          title: Name
          type: string
        observed_entity_ids:
          items:
            type: integer
          title: Observed Entity Ids
          type: array
        pillar:
          anyOf:
            - $ref: '#/components/schemas/PillarCode'
            - type: 'null'
        root_entity_id:
          exclusiveMinimum: 0
          title: Root Entity Id
          type: integer
        severity:
          $ref: '#/components/schemas/SignalSeverity'
        signal_multiplier:
          anyOf:
            - type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Signal Multiplier
        version:
          title: Version
          type: string
      required:
        - code
        - name
        - version
        - root_entity_id
        - assessed_entity_id
        - identified
        - severity
        - pillar
        - base_score
        - signal_multiplier
        - adjusted_score
      title: SignalResult
      type: object
    PillarRiskBreakdown:
      description: Auditable risk contribution for one measurable pillar.
      properties:
        base_points:
          anyOf:
            - type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Base Points
        identified_signal_codes:
          items:
            type: string
          title: Identified Signal Codes
          type: array
        pillar:
          $ref: '#/components/schemas/PillarCode'
        subscore:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Subscore
        weight:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Weight
        weighted_score:
          anyOf:
            - minimum: 0
              type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Weighted Score
      required:
        - pillar
        - weight
        - base_points
        - subscore
        - weighted_score
      title: PillarRiskBreakdown
      type: object
    RiskColor:
      enum:
        - green
        - yellow
        - orange
        - red
      title: RiskColor
      type: string
    RiskLevel:
      description: Final AML risk classes used by the methodology scoring layer.
      enum:
        - low
        - medium
        - high
        - critical
      title: RiskLevel
      type: string
    PillarSignalCount:
      properties:
        count:
          title: Count
          type: integer
        score_sum:
          anyOf:
            - type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Score Sum
      required:
        - count
        - score_sum
      title: PillarSignalCount
      type: object
      description: Contagem de sinais para um pilar de risco específico.
    PersonEducationLevel:
      enum:
        - illiterate
        - reads_writes
        - elementary_incomplete
        - elementary_complete
        - secondary_incomplete
        - secondary_complete
        - higher_incomplete
        - higher_complete
      title: PersonEducationLevel
      type: string
    EntityType:
      enum:
        - person
        - organization
        - government_agency
        - financial_institution
        - political_party
        - foreign_entity
        - vessel
        - aircraft
      title: EntityType
      type: string
    EstablishmentType:
      enum:
        - headquarters
        - branch
      title: EstablishmentType
      type: string
    PersonGender:
      enum:
        - M
        - F
      title: PersonGender
      type: string
    OrganizationGovernmentBranch:
      enum:
        - executivo
        - legislativo
        - judiciario
      title: OrganizationGovernmentBranch
      type: string
    PersonMaritalStatus:
      enum:
        - single
        - married
        - divorced
        - widowed
        - stable_union
        - separated
      title: PersonMaritalStatus
      type: string
    OrganizationCategory:
      enum:
        - private_company
        - public_company
        - government_agency
        - nonprofit
        - association
        - foundation
        - political_party
        - financial_institution
        - foreign_company
        - other
      title: OrganizationCategory
      type: string
    PersonRaceColor:
      enum:
        - white
        - black
        - brown
        - yellow
        - indigenous
      title: PersonRaceColor
      type: string
    OrganizationUnitStatus:
      enum:
        - ativo
        - extinto
        - em_liquidacao
      title: OrganizationUnitStatus
      type: string
    OrganizationUnitType:
      enum:
        - orgao
        - entidade
        - unidade_adm
        - colegiado
      title: OrganizationUnitType
      type: string
    BandFloorSourceType:
      enum:
        - signal
        - meta_rule
      title: BandFloorSourceType
      type: string
    AppliedModifier:
      description: Modifier that was applied to a signal, technique, or global pillar.
      properties:
        code:
          title: Code
          type: string
        direction:
          $ref: '#/components/schemas/ModifierDirection'
        evidences:
          items:
            $ref: '#/components/schemas/Evidence'
          title: Evidences
          type: array
        limitations:
          items:
            $ref: '#/components/schemas/DataRequirement'
          title: Limitations
          type: array
        multiplier_delta:
          anyOf:
            - type: number
            - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: string
          title: Multiplier Delta
        name:
          title: Name
          type: string
        scope:
          $ref: '#/components/schemas/ModifierScope'
      required:
        - code
        - name
        - scope
        - direction
        - multiplier_delta
      title: AppliedModifier
      type: object
    Evidence:
      additionalProperties: false
      description: >-
        Generic evidence object with explicit key, label, type, and original
        payload.


        This contract is intentionally generic so each signal/modifier can
        attach

        the actual objects used as evidence (for example, transactions or
        process

        records) without forcing a rigid schema at this layer.
      properties:
        content:
          title: Content
        description:
          title: Description
          type: string
        key:
          title: Key
          type: string
        label:
          title: Label
          type: string
        metadata:
          additionalProperties: true
          title: Metadata
          type: object
        type:
          $ref: '#/components/schemas/EvidenceType'
      required:
        - key
        - label
        - description
        - type
        - content
      title: Evidence
      type: object
    SignalKind:
      description: Methodology signal execution kind.
      enum:
        - observable
        - meta
      title: SignalKind
      type: string
    DataRequirement:
      description: >-
        Structured data requirement for methodology entities.


        `fields` lists the expected context fields and `justification` records
        why that

        field set is required for detector or modifier behavior.
      properties:
        fields:
          items:
            type: string
          title: Fields
          type: array
        justification:
          default: ''
          title: Justification
          type: string
      title: DataRequirement
      type: object
    PillarCode:
      description: Official Motor 1 v1 measurable AML risk pillars.
      enum:
        - sanc
        - estru
        - jud
        - pep
        - juris
      title: PillarCode
      type: string
    SignalSeverity:
      description: Base severity level used by Motor 1 signals and legacy methodology code.
      enum:
        - clean
        - enrichment
        - low
        - medium
        - medium_high
        - high
        - very_high
        - critical
      title: SignalSeverity
      type: string
    ModifierDirection:
      description: Whether a modifier increases or reduces risk strength.
      enum:
        - aggravate
        - attenuate
      title: ModifierDirection
      type: string
    ModifierScope:
      description: Calculation level where an aggravant or attenuant acts.
      enum:
        - signal
        - technique
        - global_pillar
      title: ModifierScope
      type: string
    EvidenceType:
      description: High-level category of evidence payload used by methodology evaluations.
      enum:
        - transaction
        - transaction_groups
        - corporate_ownership_partners
        - ubo_resolution
        - corporate_participation_fanout
        - serial_company_opening
        - organization_stability
        - qsa_full_replacement
        - simples_exclusion
        - cadastral_precariousness
        - thin_file_routing
        - mlro_escalation
        - sanctionary
        - organization_registration
        - cnae_mismatch
        - cadastral_cnae_mismatch
        - sensitive_activity_cnae
        - nonprofit_legal_nature
        - isolated_controller_interposition
        - control_cycle
        - process
        - warrant
        - sanction
        - restriction
        - watchlist_entry
        - territorial_jurisdiction
        - official_publication_control_intent
        - public_service_link
        - public_servant_private_management
        - public_quarantine_private_activity
        - risk_composition
        - political_exposure
        - official_publication
        - administrative_condemnation
        - regulatory_enforcement
        - object
        - other
      title: EvidenceType
      type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````