{
  "openapi": "3.0.3",
  "info": {
    "title": "Jev + NSR Public Industry Demo",
    "version": "1.3.0",
    "description": "Public sample scenarios. Live runs require a request-only Jev key; no StateSet login. Fixed policy and evidence. No business actions are executed. Use sample text only; demo decision records may be retained. Download /jev/starter.py or /jev/starter.mjs for a runnable agent client. No-key walkthrough: /jev/example.json (illustrative, never a live response). Supply a unique Idempotency-Key for each intentional inference. Same key and inputs returns the recorded result for 24 hours; changed inputs return 409. Pending or unknown work is never rerun automatically. Inputs and results are encrypted and retained for 24 hours; Jev keys are not stored in these records. GET /api/jev/requests/{idempotencyKey} with the same Jev key retrieves status without inference."
  },
  "servers": [
    {
      "url": "https://nsr.stateset.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "JevKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Jev-Api-Key",
        "description": "Your Jev API key. Used only for this live request; never place it in a URL."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "next_action": {
                "type": "string"
              },
              "safe_to_auto_retry": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "retry_after_seconds": {
                "type": "integer",
                "minimum": 0
              },
              "request_id": {
                "type": "string",
                "description": "Server-generated correlation ID; also in X-Request-ID."
              }
            },
            "required": [
              "code",
              "message",
              "next_action",
              "safe_to_auto_retry"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Request": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "industry",
          "scenario"
        ],
        "properties": {
          "industry": {
            "type": "string",
            "enum": [
              "financial_services",
              "travel_hospitality",
              "healthcare",
              "retail",
              "telecommunications",
              "technology",
              "media"
            ]
          },
          "scenario": {
            "type": "string",
            "example": "RT-4001",
            "description": "Scenario id from the catalog."
          },
          "message": {
            "type": "string",
            "maxLength": 4000,
            "description": "Optional replacement customer message; otherwise the sample message is used."
          }
        }
      },
      "Decision": {
        "type": "object",
        "required": [
          "industry",
          "scenario",
          "mode",
          "result",
          "expectation_applicable"
        ],
        "properties": {
          "industry": {
            "type": "string"
          },
          "scenario": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live"
            ]
          },
          "fixture_expectation": {
            "type": "string"
          },
          "result": {
            "$ref": "#/components/schemas/Result"
          },
          "expectation_applicable": {
            "type": "boolean",
            "description": "False when message differs from the original scenario. Do not compare custom messages against the original expected outcome."
          },
          "request_id": {
            "type": "string",
            "description": "Server-generated correlation ID; also in X-Request-ID."
          },
          "schema_version": {
            "type": "string"
          }
        }
      },
      "Predicate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "args": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                }
              ],
              "nullable": true
            }
          },
          "negated": {
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "args"
        ]
      },
      "Judgment": {
        "type": "object",
        "properties": {
          "predicate": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "noul",
              "choice",
              "score"
            ]
          },
          "value": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ]
          },
          "confidence": {
            "type": "number"
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            }
          },
          "fact": {
            "type": "string"
          },
          "readings": {
            "type": "integer",
            "minimum": 0
          },
          "agreement": {
            "type": "number"
          },
          "samples": {
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "origin": {
            "type": "string"
          },
          "round": {
            "type": "integer",
            "minimum": 0
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "predicate",
          "value"
        ]
      },
      "Judgments": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "judgments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Judgment"
            }
          },
          "input_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "latency_ms": {
            "type": "integer",
            "minimum": 0
          },
          "rounds": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "model",
          "judgments"
        ]
      },
      "Derivation": {
        "type": "object",
        "properties": {
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "rule": {
                  "type": "string"
                },
                "premises": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "conclusions": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "rule",
                "premises",
                "conclusions"
              ]
            }
          },
          "authorizing_predicate": {
            "type": "string"
          },
          "replayable": {
            "type": "boolean"
          },
          "org_facts_used": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cited_org_rules": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "conditions": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "conclusions": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "name",
                "conditions",
                "conclusions"
              ]
            }
          }
        },
        "required": [
          "steps",
          "replayable"
        ]
      },
      "Proof": {
        "type": "object",
        "properties": {
          "cited_rules": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "symbolic_steps": {
            "type": "integer",
            "minimum": 0
          },
          "neural_steps": {
            "type": "integer",
            "minimum": 0
          },
          "planner_steps": {
            "type": "integer",
            "minimum": 0
          },
          "proof_score": {
            "type": "number"
          },
          "proof_status": {
            "type": "string"
          },
          "derivation": {
            "$ref": "#/components/schemas/Derivation"
          },
          "request_policy_hash": {
            "type": "string"
          }
        },
        "required": [
          "cited_rules"
        ]
      },
      "Evidence": {
        "type": "object",
        "properties": {
          "claims": {
            "type": "integer",
            "minimum": 0
          },
          "accepted": {
            "type": "integer",
            "minimum": 0
          },
          "requires_human_review": {
            "type": "boolean"
          },
          "unknown": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rejected": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "claim": {
                  "type": "string"
                },
                "predicate": {
                  "type": "string"
                },
                "subject": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                }
              },
              "required": [
                "predicate",
                "reason"
              ]
            }
          },
          "conflicts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "predicate": {
                  "type": "string"
                },
                "subject": {
                  "type": "string"
                },
                "claims": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "resolution": {
                  "type": "string"
                },
                "accepted": {
                  "type": "string"
                }
              },
              "required": [
                "predicate",
                "resolution"
              ]
            }
          }
        },
        "required": [
          "accepted"
        ]
      },
      "Refusal": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string"
          },
          "requires_human_review": {
            "type": "boolean"
          },
          "missing_facts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "predicate": {
                  "type": "string"
                },
                "args": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "needed_by_rule": {
                  "type": "string"
                },
                "question": {
                  "type": "string"
                },
                "resolves_with": {
                  "type": "object",
                  "properties": {
                    "predicate": {
                      "$ref": "#/components/schemas/Predicate"
                    }
                  },
                  "required": [
                    "predicate"
                  ]
                }
              },
              "required": [
                "predicate",
                "args",
                "needed_by_rule",
                "question"
              ]
            }
          },
          "failed_constraints": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "constraint": {
                  "type": "string"
                },
                "needed_by_rule": {
                  "type": "string"
                },
                "explanation": {
                  "type": "string"
                }
              },
              "required": [
                "constraint",
                "needed_by_rule",
                "explanation"
              ]
            }
          }
        },
        "required": [
          "reason"
        ]
      },
      "Routing": {
        "type": "object",
        "properties": {
          "band": {
            "type": "string",
            "enum": [
              "act",
              "confirm",
              "escalate"
            ]
          },
          "effective_confidence": {
            "type": "number"
          },
          "basis": {
            "type": "string"
          },
          "act_threshold": {
            "type": "number"
          },
          "confirm_threshold": {
            "type": "number"
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "band"
        ]
      },
      "Result": {
        "type": "object",
        "properties": {
          "decision": {
            "type": "string",
            "enum": [
              "approved",
              "denied",
              "refused"
            ]
          },
          "plain_explanation": {
            "type": "string"
          },
          "rationale": {
            "type": "string"
          },
          "judgments": {
            "$ref": "#/components/schemas/Judgments"
          },
          "proof": {
            "$ref": "#/components/schemas/Proof"
          },
          "evidence": {
            "$ref": "#/components/schemas/Evidence"
          },
          "refusal": {
            "$ref": "#/components/schemas/Refusal"
          },
          "routing": {
            "$ref": "#/components/schemas/Routing"
          }
        },
        "required": [
          "decision",
          "judgments"
        ]
      },
      "Fact": {
        "type": "object",
        "properties": {
          "predicate": {
            "$ref": "#/components/schemas/Predicate"
          },
          "provenance": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "trust": {
                "type": "string"
              },
              "observed_at": {
                "type": "string"
              },
              "valid_until": {
                "type": "string"
              },
              "valid_from": {
                "type": "string"
              }
            }
          },
          "age_secs": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "predicate"
        ]
      },
      "Rule": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "effect": {
            "type": "string"
          },
          "if": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Predicate"
            }
          },
          "then": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Predicate"
            }
          }
        },
        "required": [
          "name",
          "if",
          "then"
        ]
      },
      "Scenario": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "expectation": {
            "type": "string",
            "enum": [
              "approved",
              "denied",
              "refused",
              "not_approved"
            ]
          },
          "human_review": {
            "type": "boolean"
          },
          "challenge": {
            "type": "string",
            "nullable": true
          },
          "facts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Fact"
            }
          }
        },
        "required": [
          "id",
          "name",
          "message",
          "expectation",
          "facts"
        ]
      },
      "Pack": {
        "type": "object",
        "properties": {
          "industry": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "definition": {
            "type": "string"
          },
          "rules": {
            "type": "integer",
            "minimum": 0
          },
          "judgments": {
            "type": "integer",
            "minimum": 0
          },
          "policy": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Rule"
            }
          },
          "questions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "predicate": {
                  "type": "string"
                },
                "instructions": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "complement": {
                  "type": "string"
                },
                "criteria": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "predicate",
                "instructions",
                "type"
              ]
            }
          },
          "source_trust": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "premise_requirements": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "min_trust": {
                  "type": "string"
                },
                "functional": {
                  "type": "boolean"
                },
                "max_age_secs": {
                  "type": "integer",
                  "minimum": 0
                },
                "on_conflict": {
                  "type": "string"
                }
              }
            }
          },
          "scenarios": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scenario"
            }
          }
        },
        "required": [
          "industry",
          "scenarios",
          "policy",
          "questions",
          "source_trust"
        ]
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer",
            "minimum": 0
          },
          "live_available": {
            "type": "boolean"
          },
          "requires_jev_key": {
            "type": "boolean"
          },
          "model": {
            "type": "string"
          },
          "max_message_chars": {
            "type": "integer",
            "minimum": 0
          },
          "openapi": {
            "type": "string"
          },
          "agent_instructions": {
            "type": "string"
          },
          "example": {
            "type": "string"
          },
          "starter_kits": {
            "type": "object",
            "properties": {
              "python": {
                "type": "string"
              },
              "javascript": {
                "type": "string"
              }
            }
          },
          "packs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Pack"
            }
          },
          "schema_version": {
            "type": "string"
          },
          "capabilities": {
            "type": "string"
          }
        },
        "required": [
          "live_available",
          "packs"
        ]
      }
    }
  },
  "paths": {
    "/api/jev/catalog": {
      "get": {
        "operationId": "listIndustryScenarios",
        "summary": "Discover all public industry packs and scenario messages",
        "responses": {
          "200": {
            "description": "Catalog, fixture expectations, and live availability",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/jev/decisions": {
      "post": {
        "operationId": "runIndustryScenario",
        "summary": "Run one live Jev + NSR decision using fixed demo policy and evidence",
        "description": "Jev usage is billed to your key. 30-second timeout. Limits per replica: 6 attempts/key/minute, 30 total/minute, 4 concurrent. Respect Retry-After on 429. Do not automatically retry POSTs. Fixture expectations may differ from live results.",
        "security": [
          {
            "JevKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Live engine result; refused and denied are valid outcomes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Decision"
                },
                "examples": {
                  "approved": {
                    "summary": "approved (synthetic schema example, not a recorded response)",
                    "value": {
                      "industry": "retail",
                      "scenario": "RT-4001",
                      "mode": "live",
                      "fixture_expectation": "approved",
                      "expectation_applicable": true,
                      "result": {
                        "decision": "approved",
                        "plain_explanation": "Illustration: supplied evidence satisfies the sample policy.",
                        "judgments": {
                          "model": "illustrative-only",
                          "judgments": [
                            {
                              "predicate": "damage_plausible",
                              "value": 0.93
                            }
                          ]
                        },
                        "evidence": {
                          "accepted": 3,
                          "rejected": []
                        },
                        "proof": {
                          "cited_rules": [
                            "refund_transit_damage_under_cap"
                          ]
                        }
                      }
                    }
                  },
                  "denied": {
                    "summary": "denied (synthetic schema example, not a recorded response)",
                    "value": {
                      "industry": "retail",
                      "scenario": "RT-4005",
                      "mode": "live",
                      "fixture_expectation": "denied",
                      "expectation_applicable": true,
                      "result": {
                        "decision": "denied",
                        "plain_explanation": "Illustration: a blocking policy rule applies.",
                        "judgments": {
                          "model": "illustrative-only",
                          "judgments": [
                            {
                              "predicate": "damage_plausible",
                              "value": 0.93
                            }
                          ]
                        },
                        "evidence": {
                          "accepted": 3,
                          "rejected": []
                        },
                        "proof": {
                          "cited_rules": []
                        }
                      }
                    }
                  },
                  "refused": {
                    "summary": "refused (synthetic schema example, not a recorded response)",
                    "value": {
                      "industry": "retail",
                      "scenario": "RT-4010",
                      "mode": "live",
                      "fixture_expectation": "refused",
                      "expectation_applicable": true,
                      "result": {
                        "decision": "refused",
                        "plain_explanation": "Illustration: permission cannot be established from conflicting amounts.",
                        "judgments": {
                          "model": "illustrative-only",
                          "judgments": [
                            {
                              "predicate": "damage_plausible",
                              "value": 0.93
                            }
                          ]
                        },
                        "evidence": {
                          "accepted": 3,
                          "rejected": [],
                          "requires_human_review": true
                        },
                        "proof": {
                          "cited_rules": []
                        },
                        "refusal": {
                          "reason": "Contradicting authoritative ledgers.",
                          "requires_human_review": true
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or scenario",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Missing or malformed Jev key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Browser origin rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 12 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "415": {
            "description": "JSON required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Rate or concurrency limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Demo request limit reached.",
                    "next_action": "Wait at least 60 seconds, then choose whether to run again.",
                    "safe_to_auto_retry": false,
                    "retry_after_seconds": 60
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              },
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "502": {
            "description": "Provider failure, invalid key/quota, or timeout",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Demo unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "202": {
            "description": "Original inference is still pending. Check its status; do not create a new key."
          },
          "409": {
            "description": "Key reused with changed inputs, or execution outcome unknown. No automatic inference retry."
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._:-]{8,128}$"
            },
            "description": "Unique identifier per intentional request. Retain it to recover status. Recorded engine errors replay too; admission-limit rejections are not recorded."
          }
        ]
      }
    },
    "/api/jev/capabilities": {
      "get": {
        "operationId": "getJevCapabilities",
        "summary": "Discover limits, supported inputs, and retry behavior",
        "responses": {
          "200": {
            "description": "Current deployment capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "schema_version",
                    "limits",
                    "idempotency",
                    "automatic_retries"
                  ],
                  "properties": {
                    "schema_version": {
                      "type": "string"
                    },
                    "limits": {
                      "type": "object",
                      "properties": {
                        "scope": {
                          "type": "string",
                          "enum": [
                            "process",
                            "deployment",
                            "unavailable"
                          ]
                        }
                      }
                    },
                    "idempotency": {
                      "type": "boolean",
                      "const": false
                    },
                    "automatic_retries": {
                      "type": "boolean",
                      "const": false
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated support correlation ID. Never a credential.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/jev/requests/{idempotencyKey}": {
      "get": {
        "operationId": "getJevRequestStatus",
        "security": [
          {
            "JevKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "idempotencyKey",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recorded state: pending, completed, or unknown. Completed response contains the original envelope or error."
          },
          "404": {
            "description": "Not found for this Jev key, or expired."
          },
          "503": {
            "description": "Status store unavailable; do not create another inference automatically."
          }
        }
      }
    }
  }
}