{
    "openapi":  "3.1.0",
    "info":  {
                 "title":  "MachineSignal Controlled API",
                 "version":  "0.3.0",
                 "description":  "Controlled scoring and usage API for approved B2B Italy customers. The production zero-touch order-intake contract is published separately at https://api.machinesignal.it/openapi.json and https://machinesignal.it/order-openapi.json."
             },
    "externalDocs":  {
                         "description":  "Lead opportunity score API, product fit, JSON output and machine-origin purchase path",
                         "url":  "https://machinesignal.it/api/lead-opportunity-score/"
                     },
    "x-machinesignal-discovery-pages":  [
                                              "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-product-status":  {
                                           "live_approved":  [
                                                                 "MS-DEC-250",
                                                                 "MS-ACT-25"
                                                             ],
                                           "MS-DEC-250_example_output_url":  "https://machinesignal.it/ms-dec-250-example.json",
                                           "MS-ACT-25":  "live_post_purchase_only",
                                           "MS-ACT-25_order_intent_allowed_only_with_signed_entitlement":  true,
                                           "MS-ACT-25_example_output_url":  "https://machinesignal.it/ms-act-25-example.json",
                                           "MS-ACT-25_output_contract":  {
                                                                             "product_promise":  "A complete execution-ready campaign package for exactly 25 qualified targets, prepared for a buyer-controlled CRM or workflow.",
                                                                             "package_scope":  {
                                                                                                   "target_count":  25,
                                                                                                   "deep_analysis_included":  true,
                                                                                                   "explicit_mini_check_required":  true,
                                                                                                   "cluster_strategy_required":  true,
                                                                                                   "initial_follow_up_nurturing_messages_required":  true,
                                                                                                   "crm_workflow_payload_required":  true,
                                                                                                   "campaign_sequence_days":  [
                                                                                                                                  0,
                                                                                                                                  7,
                                                                                                                                  21,
                                                                                                                                  60
                                                                                                                              ],
                                                                                                   "automatic_contact_stop_nurture_rules_required":  true,
                                                                                                   "reputation_spam_risk_assessment_required":  true,
                                                                                                   "audit_trail_required":  true
                                                                                               },
                                                                             "output_validity_rule":  "Every cited mini-check must list each explicit problem, observed evidence, recommended intervention and connected CRM/workflow action.",
                                                                             "fulfillment_release_policy":  "Fail closed unless the complete 25-target output contract and delivery readiness are verified."
                                                                         }
                                       },
    "servers":  [
                    {
                        "url":  "https://staging.machinesignal.it",
                        "description":  "Staging health and controlled API surface. Private API access requires explicit approval."
                    }
                ],
    "security":  [
                     {
                         "ApiKeyAuth":  [

                                        ]
                     }
                 ],
    "paths":  {
                  "/health":  {
                                  "get":  {
                                              "summary":  "Health check",
                                              "security":  [

                                                           ],
                                              "responses":  {
                                                                "200":  {
                                                                            "description":  "Service health response",
                                                                            "content":  {
                                                                                            "application/json":  {
                                                                                                                     "schema":  {
                                                                                                                                    "$ref":  "#/components/schemas/HealthResponse"
                                                                                                                                }
                                                                                                                 }
                                                                                        }
                                                                        }
                                                            }
                                          }
                              },
                  "/v1/lead-opportunity-score":  {
                                                     "post":  {
                                                                  "summary":  "Score one B2B Italy lead opportunity",
                                                                  "description":  "Controlled endpoint for approved B2B Italy customers. It returns a machine-readable lead decision and must not execute payment, issue invoices or contact external targets.",
                                                                  "requestBody":  {
                                                                                      "required":  true,
                                                                                      "content":  {
                                                                                                      "application/json":  {
                                                                                                                               "schema":  {
                                                                                                                                              "$ref":  "#/components/schemas/LeadOpportunityScoreRequest"
                                                                                                                                          }
                                                                                                                           }
                                                                                                  }
                                                                                  },
                                                                  "responses":  {
                                                                                    "200":  {
                                                                                                "description":  "Lead opportunity decision",
                                                                                                "content":  {
                                                                                                                "application/json":  {
                                                                                                                                         "schema":  {
                                                                                                                                                        "$ref":  "#/components/schemas/LeadOpportunityScoreResponse"
                                                                                                                                                    }
                                                                                                                                     }
                                                                                                            }
                                                                                            },
                                                                                    "401":  {
                                                                                                "description":  "Missing or invalid private API key"
                                                                                            },
                                                                                    "403":  {
                                                                                                "description":  "Customer scope is not approved for B2B Italy"
                                                                                            }
                                                                                }
                                                              }
                                                 },
                  "/v1/usage":  {
                                    "get":  {
                                                "summary":  "Read valid-output usage",
                                                "description":  "Returns usage for approved private API customers. This endpoint does not expose invoice data.",
                                                "responses":  {
                                                                  "200":  {
                                                                              "description":  "Usage response",
                                                                              "content":  {
                                                                                              "application/json":  {
                                                                                                                       "schema":  {
                                                                                                                                      "$ref":  "#/components/schemas/UsageResponse"
                                                                                                                                  }
                                                                                                                   }
                                                                                          }
                                                                          },
                                                                  "401":  {
                                                                              "description":  "Missing or invalid private API key"
                                                                          }
                                                              }
                                            }
                                }
              },
    "components":  {
                       "securitySchemes":  {
                                               "ApiKeyAuth":  {
                                                                  "type":  "apiKey",
                                                                  "in":  "header",
                                                                  "name":  "X-API-Key"
                                                              }
                                           },
                       "schemas":  {
                                       "HealthResponse":  {
                                                              "type":  "object",
                                                              "required":  [
                                                                               "ok"
                                                                           ],
                                                              "properties":  {
                                                                                 "ok":  {
                                                                                            "type":  "boolean",
                                                                                            "examples":  [
                                                                                                             true
                                                                                                         ]
                                                                                        },
                                                                                 "service":  {
                                                                                                 "type":  "string",
                                                                                                 "examples":  [
                                                                                                                  "machinesignal-staging"
                                                                                                              ]
                                                                                             }
                                                                             }
                                                          },
                                       "LeadOpportunityScoreRequest":  {
                                                                           "type":  "object",
                                                                           "required":  [
                                                                                            "domain",
                                                                                            "country_hint"
                                                                                        ],
                                                                           "properties":  {
                                                                                              "domain":  {
                                                                                                             "type":  "string",
                                                                                                             "examples":  [
                                                                                                                              "example-azienda.it"
                                                                                                                          ]
                                                                                                         },
                                                                                              "country_hint":  {
                                                                                                                   "type":  "string",
                                                                                                                   "const":  "IT"
                                                                                                               },
                                                                                              "sector_hint":  {
                                                                                                                  "type":  "string",
                                                                                                                  "examples":  [
                                                                                                                                   "B2B services"
                                                                                                                               ]
                                                                                                              },
                                                                                              "customer_scope":  {
                                                                                                                     "type":  "string",
                                                                                                                     "const":  "B2B Italy"
                                                                                                                 }
                                                                                          }
                                                                       },
                                       "LeadOpportunityScoreResponse":  {
                                                                            "type":  "object",
                                                                            "required":  [
                                                                                             "domain",
                                                                                             "opportunity_score",
                                                                                             "confidence",
                                                                                             "decision",
                                                                                             "usage"
                                                                                         ],
                                                                            "properties":  {
                                                                                               "domain":  {
                                                                                                              "type":  "string"
                                                                                                          },
                                                                                               "opportunity_score":  {
                                                                                                                         "type":  "integer",
                                                                                                                         "minimum":  0,
                                                                                                                         "maximum":  100
                                                                                                                     },
                                                                                               "confidence":  {
                                                                                                                  "type":  "number",
                                                                                                                  "minimum":  0,
                                                                                                                  "maximum":  1
                                                                                                              },
                                                                                               "decision":  {
                                                                                                                "type":  "string",
                                                                                                                "enum":  [
                                                                                                                             "discard",
                                                                                                                             "watchlist",
                                                                                                                             "review",
                                                                                                                             "prioritize"
                                                                                                                         ]
                                                                                                            },
                                                                                               "priority":  {
                                                                                                                "type":  "string",
                                                                                                                "enum":  [
                                                                                                                             "low",
                                                                                                                             "medium",
                                                                                                                             "high"
                                                                                                                         ]
                                                                                                            },
                                                                                               "reason":  {
                                                                                                              "type":  "string"
                                                                                                          },
                                                                                               "suggested_route":  {
                                                                                                                       "type":  "string"
                                                                                                                   },
                                                                                               "product_code":  {
                                                                                                                    "type":  "string",
                                                                                                                    "const":  "MS-DEC-250"
                                                                                                                },
                                                                                               "request_id":  {
                                                                                                                  "type":  "string"
                                                                                                              },
                                                                                               "decision_contract":  {
                                                                                                                         "$ref":  "#/components/schemas/DecisionContractPointer"
                                                                                                                     },
                                                                                               "usage":  {
                                                                                                             "$ref":  "#/components/schemas/UsageEnvelope"
                                                                                                         },
                                                                                               "scope":  {
                                                                                                             "type":  "string",
                                                                                                             "const":  "b2b_italy_controlled"
                                                                                                         },
                                                                                               "checkout_public":  {
                                                                                                                       "type":  "boolean",
                                                                                                                       "const":  false
                                                                                                                   },
                                                                                               "payment_executed":  {
                                                                                                                        "type":  "boolean",
                                                                                                                        "const":  false
                                                                                                                    },
                                                                                               "invoice_issued":  {
                                                                                                                      "type":  "boolean",
                                                                                                                      "const":  false
                                                                                                                  },
                                                                                               "external_contact_executed":  {
                                                                                                                                 "type":  "boolean",
                                                                                                                                 "const":  false
                                                                                                                             }
                                                                                           }
                                                                        },
                                       "DecisionContractPointer":  {
                                                                       "type":  "object",
                                                                       "properties":  {
                                                                                          "contract_url":  {
                                                                                                               "type":  "string",
                                                                                                               "format":  "uri",
                                                                                                               "examples":  [
                                                                                                                                "https://machinesignal.it/score-decision-contract.json"
                                                                                                                            ]
                                                                                                           },
                                                                                          "route":  {
                                                                                                        "type":  "string",
                                                                                                        "enum":  [
                                                                                                                     "discard",
                                                                                                                     "watchlist",
                                                                                                                     "review",
                                                                                                                     "prioritize"
                                                                                                                 ]
                                                                                                    },
                                                                                          "credit_rule":  {
                                                                                                              "type":  "string"
                                                                                                          },
                                                                                          "payment_executed":  {
                                                                                                                   "type":  "boolean",
                                                                                                                   "const":  false
                                                                                                               },
                                                                                          "invoice_issued":  {
                                                                                                                 "type":  "boolean",
                                                                                                                 "const":  false
                                                                                                             },
                                                                                          "external_contact_executed":  {
                                                                                                                            "type":  "boolean",
                                                                                                                            "const":  false
                                                                                                                        }
                                                                                      }
                                                                   },
                                       "UsageEnvelope":  {
                                                             "type":  "object",
                                                             "properties":  {
                                                                                "customer_id":  {
                                                                                                    "type":  "string"
                                                                                                },
                                                                                "ledger_persisted":  {
                                                                                                         "type":  "boolean"
                                                                                                     },
                                                                                "balances":  {
                                                                                                 "type":  "array",
                                                                                                 "items":  {
                                                                                                               "$ref":  "#/components/schemas/UsageBalance"
                                                                                                           }
                                                                                             },
                                                                                "current_event":  {
                                                                                                      "$ref":  "#/components/schemas/UsageEvent"
                                                                                                  },
                                                                                "rule":  {
                                                                                             "type":  "string"
                                                                                         },
                                                                                "real_payment_executed":  {
                                                                                                              "type":  "boolean",
                                                                                                              "const":  false
                                                                                                          },
                                                                                "external_contact_executed":  {
                                                                                                                  "type":  "boolean",
                                                                                                                  "const":  false
                                                                                                              }
                                                                            }
                                                         },
                                       "UsageBalance":  {
                                                            "type":  "object",
                                                            "properties":  {
                                                                               "product_code":  {
                                                                                                    "type":  "string",
                                                                                                    "const":  "MS-DEC-250"
                                                                                                },
                                                                               "credits_purchased":  {
                                                                                                         "type":  "integer",
                                                                                                         "examples":  [
                                                                                                                          250
                                                                                                                      ]
                                                                                                     },
                                                                               "credits_used":  {
                                                                                                    "type":  "integer",
                                                                                                    "minimum":  0
                                                                                                },
                                                                               "credits_remaining":  {
                                                                                                         "type":  "integer",
                                                                                                         "minimum":  0
                                                                                                     }
                                                                           }
                                                        },
                                       "UsageEvent":  {
                                                          "type":  "object",
                                                          "properties":  {
                                                                             "product_code":  {
                                                                                                  "type":  "string",
                                                                                                  "const":  "MS-DEC-250"
                                                                                              },
                                                                             "status":  {
                                                                                            "type":  "string",
                                                                                            "enum":  [
                                                                                                         "valid_output",
                                                                                                         "not_consumed"
                                                                                                     ]
                                                                                        },
                                                                             "credits_consumed":  {
                                                                                                      "type":  "integer",
                                                                                                      "minimum":  0
                                                                                                  },
                                                                             "request_id":  {
                                                                                                "type":  "string"
                                                                                            },
                                                                             "reason":  {
                                                                                            "type":  "string"
                                                                                        },
                                                                             "credits_remaining":  {
                                                                                                       "type":  "integer",
                                                                                                       "minimum":  0
                                                                                                   }
                                                                         }
                                                      },
                                       "UsageResponse":  {
                                                             "type":  "object",
                                                             "properties":  {
                                                                                "product_code":  {
                                                                                                     "type":  "string",
                                                                                                     "const":  "MS-DEC-250"
                                                                                                 },
                                                                                "credits_purchased":  {
                                                                                                          "type":  "integer",
                                                                                                          "examples":  [
                                                                                                                           250
                                                                                                                       ]
                                                                                                      },
                                                                                "credits_used":  {
                                                                                                     "type":  "integer"
                                                                                                 },
                                                                                "credits_remaining":  {
                                                                                                          "type":  "integer"
                                                                                                      }
                                                                            }
                                                         }
                                   }
                   },
    "tags":  [
                 {
                     "name":  "MS-ACT-25",
                     "description":  "Post-purchase-only continuation after paid and completed MS-DEC-250. Delivers a complete 25-target campaign package with Deep Analysis, explicit mini-checks, cluster strategy, message drafts, CRM/workflow payloads, sequence, automatic rules, risk assessment and audit trail. External execution remains buyer-controlled. Full synthetic example: https://machinesignal.it/ms-act-25-example.json"
                 }
             ]
}