{
  "openapi": "3.1.0",
  "info": {
    "title": "Trust OS Decision Verification API",
    "description": "API for verifying high-impact decisions before execution across payments, stablecoins, treasury workflows, AI agents, and compliance systems.",
    "version": "1.0.0",
    "contact": {
      "name": "Trust OS",
      "url": "https://trust-os.io",
      "email": "founder@trust-os.io"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://trust-os.io"
    }
  },
  "servers": [
    {
      "url": "https://trustos-core-gateway-v2-7jm9owrs.an.gateway.dev",
      "description": "Production API Gateway"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/v1/decision/verify": {
      "post": {
        "summary": "Verify a Decision",
        "description": "Submit a high-impact decision for verification. Returns a recommendation (APPROVE, REVIEW, or DENY), a risk score, and a cryptographic proof hash for audit compliance.",
        "operationId": "verifyDecision",
        "tags": ["Decisions"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionRequest"
              },
              "example": {
                "action": "stablecoin_transfer",
                "amount": 50000,
                "currency": "USDC",
                "destination": "wallet_abc",
                "source": "Payment API",
                "priority": "High",
                "metadata": {
                  "region": "SG",
                  "workflow": "merchant_settlement"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decision verified successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DecisionResponse"
                },
                "example": {
                  "decision_id": "dec_example_001",
                  "recommendation": "APPROVE",
                  "risk_score": 0.18,
                  "risk_level": "LOW",
                  "policy": "Stablecoin Settlement Policy v1.0",
                  "proof_hash": "SHA-256: 0x4a3f...9c2b",
                  "verified": true,
                  "latency_ms": 142
                }
              }
            }
          },
          "400": {
            "description": "Invalid or malformed request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "invalid_request",
                  "message": "Missing required field: action"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "unauthorized",
                  "message": "Invalid API key"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "rate_limit_exceeded",
                  "message": "Too many requests"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "internal_error",
                  "message": "Internal server error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key for authentication. Pass your key in the x-api-key header on every request."
      }
    },
    "schemas": {
      "DecisionRequest": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": {
            "type": "string",
            "description": "Decision action to verify (e.g. stablecoin_transfer, PaymentAuthorization, execute_tool)",
            "example": "stablecoin_transfer"
          },
          "amount": {
            "type": "number",
            "description": "Transaction or operation amount",
            "example": 50000
          },
          "currency": {
            "type": "string",
            "description": "Currency or asset symbol (e.g. USDC, JPY, ETH)",
            "example": "USDC"
          },
          "destination": {
            "type": "string",
            "description": "Wallet, account, counterparty, or target identifier",
            "example": "wallet_abc"
          },
          "source": {
            "type": "string",
            "description": "Originating system — Payment API, Agent Framework, etc.",
            "example": "Payment API"
          },
          "priority": {
            "type": "string",
            "description": "Risk or review priority",
            "enum": ["High", "Medium", "Low"],
            "example": "High"
          },
          "metadata": {
            "type": "object",
            "description": "Additional context fields for risk evaluation",
            "additionalProperties": true,
            "example": {
              "region": "SG",
              "workflow": "merchant_settlement"
            }
          }
        }
      },
      "DecisionResponse": {
        "type": "object",
        "required": [
          "decision_id",
          "recommendation",
          "risk_score",
          "risk_level",
          "policy",
          "proof_hash",
          "verified",
          "latency_ms"
        ],
        "properties": {
          "decision_id": {
            "type": "string",
            "description": "Unique decision identifier — store alongside every transaction for audit traceability",
            "example": "dec_example_001"
          },
          "recommendation": {
            "type": "string",
            "description": "Verification outcome — gate execution on this value",
            "enum": ["APPROVE", "REVIEW", "DENY"],
            "example": "APPROVE"
          },
          "risk_score": {
            "type": "number",
            "description": "Numeric risk evaluation from 0.0 (no risk) to 1.0 (maximum risk)",
            "minimum": 0,
            "maximum": 1,
            "example": 0.18
          },
          "risk_level": {
            "type": "string",
            "description": "Categorical risk level",
            "enum": ["LOW", "MEDIUM", "HIGH"],
            "example": "LOW"
          },
          "policy": {
            "type": "string",
            "description": "Policy name and version applied to this decision",
            "example": "Stablecoin Settlement Policy v1.0"
          },
          "proof_hash": {
            "type": "string",
            "description": "SHA-256 cryptographic proof — archive for compliance audits",
            "example": "SHA-256: 0x4a3f...9c2b"
          },
          "verified": {
            "type": "boolean",
            "description": "True when the decision was cryptographically verified",
            "example": true
          },
          "latency_ms": {
            "type": "number",
            "description": "API evaluation latency in milliseconds",
            "example": 142
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine-readable error code",
            "enum": [
              "unauthorized",
              "invalid_request",
              "rate_limit_exceeded",
              "internal_error"
            ],
            "example": "unauthorized"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error description",
            "example": "Invalid API key"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Decisions",
      "description": "Decision verification endpoints"
    }
  ]
}