{
  "swagger": "2.0",
  "info": {
    "title": "Decionis Power Automate Governance Connector",
    "version": "1.0.0",
    "description": "Call Decionis before a Microsoft Power Automate flow executes a high-stakes action."
  },
  "host": "api.decionis.com",
  "basePath": "/v1",
  "schemes": ["https"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "name": "x-api-key",
      "in": "header"
    }
  },
  "security": [{ "api_key": [] }],
  "paths": {
    "/power-automate/policy-check": {
      "post": {
        "operationId": "PolicyCheck",
        "summary": "Evaluate a governed decision before execution",
        "description": "Returns allow, block, escalate, or delay so a Power Automate flow can branch before continuing. Policy selection stays in Decionis; the flow passes business context and optionally a Policy Decision Graph key when multiple Microsoft bindings exist.",
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/PolicyCheckRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Governed outcome",
            "schema": {
              "$ref": "#/definitions/PolicyCheckResponse"
            }
          }
        }
      }
    },
    "/power-automate/capital-evaluation": {
      "post": {
        "operationId": "EvaluateCapital",
        "summary": "Evaluate Capital Multiplier opportunities",
        "description": "Evaluates value-creation opportunities (early-payment yield, capital routing, FX optimization, working-capital preservation) on a signal bundle. Returns one recommendation per opportunity with a disposition (auto_execute, approval_required, advisory, no_action) and a signed dossier id, so a flow can branch and resume on approval in Teams.",
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CapitalEvaluationRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Capital Multiplier recommendations",
            "schema": {
              "$ref": "#/definitions/CapitalEvaluationResponse"
            }
          }
        }
      }
    },
    "/power-automate/capital-recommendations": {
      "get": {
        "operationId": "ListCapitalRecommendations",
        "summary": "List recent Capital Multiplier recommendations",
        "description": "Returns recent value-creation recommendations and their human/auto outcomes for an org, newest first. A read-only audit view for the Teams app-home or a flow.",
        "parameters": [
          { "in": "query", "name": "org_id", "required": true, "type": "string", "format": "uuid" },
          { "in": "query", "name": "limit", "required": false, "type": "integer" }
        ],
        "responses": {
          "200": {
            "description": "Recent recommendations",
            "schema": { "$ref": "#/definitions/CapitalRecommendationsResponse" }
          }
        }
      }
    },
    "/power-automate/triggers/subscriptions": {
      "post": {
        "operationId": "SubscribeGovernanceEvent",
        "summary": "When a Decionis governance event occurs",
        "description": "Registers a webhook callback so Power Automate can resume when a Decionis governance event is emitted.",
        "x-ms-trigger": "single",
        "x-ms-trigger-hint": "Create a flow run when Decionis posts a governance event callback.",
        "x-ms-notification-content": {
          "description": "Governance event callback payload",
          "schema": {
            "$ref": "#/definitions/TriggerNotification"
          }
        },
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TriggerSubscriptionRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Subscription created",
            "headers": {
              "Location": {
                "type": "string",
                "description": "Delete this URL to unsubscribe the webhook trigger."
              }
            },
            "schema": {
              "$ref": "#/definitions/TriggerSubscriptionResponse"
            }
          }
        }
      }
    },
    "/power-automate/triggers/subscriptions/{subscriptionId}": {
      "delete": {
        "operationId": "UnsubscribeGovernanceEvent",
        "summary": "Remove a Decionis governance webhook trigger subscription",
        "parameters": [
          {
            "name": "subscriptionId",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uuid"
          }
        ],
        "responses": {
          "204": {
            "description": "Subscription removed"
          }
        }
      }
    }
  },
  "definitions": {
    "PolicyCheckRequest": {
      "type": "object",
      "required": ["org_id"],
      "properties": {
        "org_id": { "type": "string", "format": "uuid" },
        "policy_graph_key": {
          "type": "string",
          "description": "Optional Decionis Policy Decision Graph key. Use this only when more than one active Microsoft distribution binding exists for the org."
        },
        "decision_band": { "type": "string" },
        "transaction_type": { "type": "string" },
        "amount": { "type": "number" },
        "risk_score": { "type": "number" },
        "channel": { "type": "string" },
        "requested_action": { "type": "string" },
        "source_system": { "type": "string" },
        "record_id": { "type": "string" },
        "idempotency_key": { "type": "string" },
        "context": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "PolicyCheckResponse": {
      "type": "object",
      "properties": {
        "verdict": {
          "type": "string",
          "enum": ["allow", "block", "escalate", "delay"]
        },
        "flow_action": {
          "type": "string",
          "enum": ["execute", "block", "escalate", "delay"]
        },
        "continue_flow": { "type": "boolean" },
        "escalate_in_teams": { "type": "boolean" },
        "block_execution": { "type": "boolean" },
        "delay_execution": { "type": "boolean" },
        "ignore_request": { "type": "boolean" },
        "risk": {
          "type": "string",
          "enum": ["LOW", "MEDIUM", "HIGH"]
        },
        "reason": { "type": "string" },
        "required_human_action": { "type": "string" },
        "outcome": {
          "type": "string",
          "enum": ["APPROVE", "ESCALATE", "REJECT", "REVIEW"]
        },
        "confidence": { "type": "number" },
        "confidence_percent": { "type": "string" },
        "mode": { "type": "string" },
        "policy_version": { "type": "string" },
        "objective_profile": { "type": "string" },
        "dossier_id": { "type": "string", "format": "uuid" },
        "dossier_api_path": { "type": "string" },
        "verification_url": { "type": "string" },
        "verification": {
          "type": "object",
          "properties": {
            "verification_api_path": { "type": "string" },
            "verification_url": { "type": "string" },
            "verification_page_url": { "type": "string" },
            "signature_algorithm": { "type": "string" },
            "signature": { "type": "string" },
            "asymmetric_proof": {
              "type": "object",
              "x-nullable": true
            },
            "asymmetric_proof_bundle": {
              "type": "object",
              "x-nullable": true
            }
          }
        },
        "reason_codes": {
          "type": "array",
          "items": { "type": "string" }
        },
        "evaluation_id": { "type": "string", "format": "uuid" },
        "decision_resolution_id": {
          "type": "string",
          "format": "uuid",
          "x-nullable": true
        },
        "ledger_entry_id": {
          "type": "string",
          "format": "uuid",
          "x-nullable": true
        },
        "ledger_entry_hash": {
          "type": "string",
          "x-nullable": true
        },
        "fallback_to_legacy": { "type": "boolean" },
        "fallback_reason": {
          "type": "string",
          "x-nullable": true
        },
        "reconciliation_required": { "type": "boolean" },
        "reconciliation_status": { "type": "string" },
        "idempotent_replay": { "type": "boolean" },
        "policy_binding": {
          "type": "object",
          "properties": {
            "graph_key": { "type": "string" },
            "graph_name": { "type": "string" },
            "workflow_key": { "type": "string" },
            "mode": { "type": "string" }
          }
        },
        "review_in_teams_url": { "type": "string" },
        "decision_dossier": {
          "type": "object",
          "properties": {
            "dossier_id": { "type": "string", "format": "uuid" },
            "policy_version": { "type": "string" },
            "verdict": {
              "type": "string",
              "enum": ["allow", "block", "escalate", "delay"]
            },
            "risk": {
              "type": "string",
              "enum": ["LOW", "MEDIUM", "HIGH"]
            },
            "reason": { "type": "string" },
            "required_human_action": { "type": "string" },
            "verification_url": { "type": "string" },
            "dossier_api_path": { "type": "string" }
          }
        },
        "summary": { "type": "string" }
      }
    },
    "TriggerSubscriptionRequest": {
      "type": "object",
      "required": ["org_id", "event_name", "notification_url"],
      "properties": {
        "org_id": { "type": "string", "format": "uuid" },
        "event_name": {
          "type": "string",
          "enum": [
            "decisioning.v2.ran",
            "finance.routing.status.updated",
            "finance.routing.override.submitted",
            "finance.routing.override.reviewed",
            "capital.recommendation.created"
          ]
        },
        "notification_url": {
          "type": "string",
          "x-ms-notification-url": true
        },
        "workflow_name": { "type": "string" },
        "connection_reference": { "type": "string" }
      }
    },
    "TriggerSubscriptionResponse": {
      "type": "object",
      "properties": {
        "subscription": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "format": "uuid" },
            "org_id": { "type": "string", "format": "uuid" },
            "event_name": { "type": "string" },
            "notification_url": { "type": "string" },
            "status": { "type": "string" },
            "workflow_name": {
              "type": "string",
              "x-nullable": true
            },
            "connection_reference": {
              "type": "string",
              "x-nullable": true
            },
            "created_at": { "type": "string" },
            "updated_at": { "type": "string" }
          }
        }
      }
    },
    "TriggerNotification": {
      "type": "object",
      "properties": {
        "trigger_delivery_id": { "type": "string", "format": "uuid" },
        "subscription_id": { "type": "string", "format": "uuid" },
        "org_id": { "type": "string", "format": "uuid" },
        "event_name": { "type": "string" },
        "event_key": { "type": "string" },
        "triggered_at": { "type": "string" },
        "event_payload": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "CapitalEvaluationRequest": {
      "type": "object",
      "required": ["org_id", "signal_bundle"],
      "properties": {
        "org_id": { "type": "string", "format": "uuid" },
        "platform": {
          "type": "string",
          "enum": ["microsoft", "sap", "shopify", "default"],
          "description": "Originating surface; selects the localized copy. Defaults to microsoft."
        },
        "requested_mode": {
          "type": "string",
          "enum": ["shadow", "advisory", "autonomous"],
          "description": "May only make the org's configured posture more conservative, never escalate it."
        },
        "signal_bundle": {
          "type": "object",
          "description": "Capability signal bundle. Each capability is optional; the engine fails closed on incomplete signals.",
          "additionalProperties": true
        }
      }
    },
    "CapitalEvaluationResponse": {
      "type": "object",
      "properties": {
        "execution_mode": { "type": "string" },
        "policy_version": { "type": "string" },
        "recommendation_count": { "type": "integer" },
        "total_value_usd": { "type": "number" },
        "review_in_teams_url": { "type": "string" },
        "recommendations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "capability": { "type": "string" },
              "action": { "type": "string" },
              "disposition": {
                "type": "string",
                "enum": ["auto_execute", "approval_required", "advisory", "no_action"]
              },
              "value_usd": { "type": "number" },
              "confidence": { "type": "number" },
              "requires_credentials": { "type": "boolean" },
              "title": { "type": "string" },
              "body": { "type": "string" },
              "cta": { "type": "string" },
              "dossier_id": { "type": "string" },
              "canonical_sha256": { "type": "string" },
              "signature": { "type": "string" },
              "verification_url": { "type": "string" },
              "resource_kind": { "type": "string" },
              "resource_id": { "type": "string" }
            }
          }
        }
      }
    },
    "CapitalRecommendationsResponse": {
      "type": "object",
      "properties": {
        "count": { "type": "integer" },
        "recommendations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "dossierId": { "type": "string" },
              "capability": { "type": "string" },
              "action": { "type": "string" },
              "disposition": { "type": "string" },
              "valueUsd": { "type": "number" },
              "confidence": { "type": "number" },
              "platform": { "type": "string" },
              "resourceKind": { "type": "string" },
              "resourceId": { "type": "string" },
              "executionMode": { "type": "string" },
              "createdAt": { "type": "string" },
              "outcome": {
                "type": "object",
                "properties": {
                  "action": { "type": "string" },
                  "executed": { "type": "boolean" },
                  "dryRun": { "type": "boolean" },
                  "at": { "type": "string" }
                }
              }
            }
          }
        }
      }
    }
  }
}