machinesignal-it Previews API

openapi: 3.2.0
info:
  title: MachineSignal controlled B2B Italy order intake Previews API
  version: 2026-08-24.mini-dec-preview.v2
  description: Zero-touch B2B Italy flow for MS-DEC-250 and its conditional MS-ACT-25 continuation. ACT is available only to the same buyer after a paid, completed DEC delivery and a signed entitlement for exactly 25 qualified records.
servers:
- url: https://api.machinesignal.it
tags:
- name: Previews
paths:
  /v1/previews/public-readiness:
    post:
      operationId: createMachineSignalMiniDecPreview
      summary: Compare one to three Italian B2B company domains with a limited DEC preview
      description: Free, non-commercial comparison based only on observable public-homepage signals. It ranks only the submitted domains and illustrates part of the DEC method; it is not the paid MS-DEC-250 analysis, creates no order or checkout, accepts no personal data and does not persist submitted domains in the preview service.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicPreviewRequest'
      responses:
        '200':
          description: Limited DEC-method comparison and a synthetic DEC output illustration; no full commercial decision or side effect.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPreviewResponse'
        '400':
          description: Invalid request or missing confirmations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Domain cannot be inspected safely or does not resolve to a public website.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Public preview rate limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Previews
components:
  schemas:
    MiniDecPreview:
      type: object
      additionalProperties: false
      required:
      - rank
      - opportunity_signal_score
      - confidence
      - priority
      - decision
      - reason
      - evidence_coverage
      - source_scope
      - comparison_scope
      - not_full_commercial_decision
      properties:
        rank:
          type: integer
          minimum: 1
          maximum: 3
        opportunity_signal_score:
          type: integer
          minimum: 0
          maximum: 100
        confidence:
          type: number
          minimum: 0
          maximum: 0.65
        priority:
          enum:
          - high
          - medium
          - low
        decision:
          enum:
          - prioritize_for_full_dec
          - review_in_full_dec
          - defer_until_more_evidence
        reason:
          type: string
        evidence_coverage:
          type: object
          additionalProperties: false
          required:
          - positive
          - checked
          properties:
            positive:
              type: integer
              minimum: 0
            checked:
              type: integer
              minimum: 1
        source_scope:
          const: public_homepage_only
        comparison_scope:
          const: submitted_domains_only
        not_full_commercial_decision:
          const: true
    ErrorResponse:
      type: object
      additionalProperties: true
      description: Fail-closed machine-readable error. No checkout, payment, invoice, dataset or artifact is released on failure.
      properties:
        decision:
          type: string
        code:
          type: string
        error:
          type: string
        message:
          type: string
    PublicPreviewResponse:
      type: object
      additionalProperties: false
      required:
      - protocol
      - mode
      - commercial_scope
      - submitted_domain_count
      - observed_domain_count
      - results
      - dec_illustration
      - boundaries
      - next_step
      properties:
        protocol:
          const: machinesignal_mini_dec_preview_v2
        mode:
          const: free_limited_dec_preview
        commercial_scope:
          const: B2B_Italy_only
        submitted_domain_count:
          type: integer
          minimum: 1
          maximum: 3
        observed_domain_count:
          type: integer
          minimum: 0
          maximum: 3
        results:
          type: array
          minItems: 1
          maxItems: 3
          items:
            $ref: '#/components/schemas/PublicPreviewResult'
        dec_illustration:
          type: object
          additionalProperties: true
        boundaries:
          type: object
          additionalProperties: true
          properties:
            preview_is_full_ms_dec_250:
              const: false
            preview_is_limited_dec_method_illustration:
              const: true
            preview_ranks_only_submitted_domains:
              const: true
            order_created:
              const: false
            checkout_created:
              const: false
            payment_executed:
              const: false
            submitted_domains_persisted_by_preview:
              const: false
        next_step:
          type: string
    PublicPreviewResult:
      type: object
      additionalProperties: true
      required:
      - status
      - domain
      - public_readiness_score
      - findings
      - mini_dec_preview
      - commercial_decision_generated
      - full_dec_analysis_generated
      properties:
        status:
          enum:
          - observed
          - not_observed
        domain:
          type: string
        public_readiness_score:
          oneOf:
          - type: integer
            minimum: 0
            maximum: 100
          - type: 'null'
        observed_title:
          oneOf:
          - type: string
          - type: 'null'
        observed_description:
          oneOf:
          - type: string
          - type: 'null'
        findings:
          type: array
          items:
            $ref: '#/components/schemas/PublicPreviewFinding'
        mini_dec_preview:
          oneOf:
          - $ref: '#/components/schemas/MiniDecPreview'
          - type: 'null'
        interpretation:
          type: string
        reason:
          type: string
        commercial_decision_generated:
          const: false
        full_dec_analysis_generated:
          const: false
    PublicPreviewRequest:
      type: object
      additionalProperties: false
      required:
      - domains
      - b2b_italy_confirmation
      - company_only_confirmation
      - privacy_acknowledged
      properties:
        domains:
          type: array
          minItems: 1
          maxItems: 3
          uniqueItems: true
          items:
            type: string
            description: Public company domain only; no people, email addresses, credentials or private hosts.
        b2b_italy_confirmation:
          const: true
        company_only_confirmation:
          const: true
        privacy_acknowledged:
          const: true
    PublicPreviewFinding:
      type: object
      additionalProperties: false
      required:
      - check
      - observed
      properties:
        check:
          type: string
        observed:
          oneOf:
          - type: boolean
          - type: integer
          - type: string
externalDocs:
  description: Lead opportunity score API, exact product fit, JSON output and machine-origin purchase path
  url: https://machinesignal.it/api/lead-opportunity-score/
x-machinesignal-discovery-pages:
- https://machinesignal.it/it/prova/
- https://machinesignal.it/api/lead-opportunity-score/
- https://machinesignal.it/resources/lead-decision-api-b2b-italy/
- https://machinesignal.it/risorse/prioritizzazione-aziende-target-api/
- https://machinesignal.it/risorse/analisi-mercato-potenziale-api/
x-machinesignal-safety:
  live_product_chain:
  - MS-DEC-250
  - MS-ACT-25 post-purchase only
  b2b_italy_only: true
  free_public_preview_enabled: true
  free_public_preview_max_domains: 3
  free_public_preview_is_ms_dec_250: false
  free_public_preview_is_limited_dec_method_illustration: true
  free_public_preview_ranks_only_submitted_domains: true
  free_public_preview_persists_submitted_domains: false
  free_public_preview_creates_order_or_checkout: false
  public_checkout: false
  buyer_specific_checkout_after_validation: true
  dataset_upload_authorized_at_intake: false
  dataset_upload_authorized_after_verified_payment: true
  payment_executed_at_intake: false
  invoice_or_sdi_executed_at_intake: false
  invoice_and_sdi_automatic_after_verified_payment: true
  normal_order_human_intervention_required: false
  ms_act_25_requires_paid_completed_dec_entitlement: true
  ms_act_25_price_eur: 399
  ms_act_25_stamp_duty_eur: 2
  ms_act_25_total_due_eur: 401
  ms_act_25_target_count: 25