{
  "openapi": "3.1.0",
  "info": {
    "title": "Passpod Trust Action API",
    "version": "0.2.1",
    "summary": "Receipt-backed API for sensitive digital actions.",
    "description": "The Passpod Trust Action API helps teams normalize sensitive action requests, check customer policy, require consent or owner approval when needed, sign a business decision, and expose safe receipt state for DIDX verification."
  },
  "servers": [
    {
      "url": "https://api.passpal.app",
      "description": "Passpod Trust Action API gateway"
    },
    {
      "url": "https://remote-worker-trustpass-api.didxdomain.workers.dev",
      "description": "Current live Remote Worker TrustPass module"
    }
  ],
  "tags": [
    {
      "name": "Trust Actions",
      "description": "Receipt-backed sensitive action control."
    },
    {
      "name": "Receipts",
      "description": "Safe receipt state verification."
    },
    {
      "name": "Remote Worker TrustPass",
      "description": "Consent-bound remote worker readiness receipts."
    },
    {
      "name": "System",
      "description": "Health checks."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["System"],
        "summary": "Check API health",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "API is reachable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/trust-actions/commit": {
      "post": {
        "tags": ["Trust Actions"],
        "summary": "Commit a trust action receipt",
        "description": "Creates a receipt-backed decision for a sensitive action. Preview modules include AgentTrust Sensitive Action Control, Vendor Access Receipts, and Transaction Trust Receipts.",
        "operationId": "commitTrustAction",
        "security": [
          {
            "PilotKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrustActionRequest"
              },
              "examples": {
                "agentDelete": {
                  "summary": "Blocked destructive AI-agent action",
                  "value": {
                    "receipt_type": "trust_action_receipt",
                    "scenario_id": "agent_delete",
                    "module": "AgentTrust Sensitive Action Control",
                    "actor": "agent-88",
                    "subject": "production_records",
                    "action": "delete_production_records",
                    "approval": "break_glass_approval_required",
                    "evidence": [
                      "agent_registered",
                      "destructive_scope_detected",
                      "production_system_detected",
                      "no_break_glass_receipt"
                    ],
                    "requested_result": "BLOCKED",
                    "risk_label": "Destructive production action",
                    "customer_owns_data": true,
                    "customer_signs_decision": true,
                    "didx_state_only": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Receipt result returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrustActionResponse"
                }
              }
            }
          },
          "202": {
            "description": "Review required before execution."
          },
          "400": {
            "description": "Invalid request payload."
          },
          "401": {
            "description": "Missing or invalid pilot key."
          },
          "403": {
            "description": "Policy blocked the action."
          },
          "409": {
            "description": "Receipt state conflict."
          }
        }
      }
    },
    "/v1/trust-actions/{receipt_id}/receipt": {
      "get": {
        "tags": ["Receipts"],
        "summary": "Verify trust action receipt state",
        "operationId": "getTrustActionReceipt",
        "parameters": [
          {
            "name": "receipt_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "tar_demo_01"
          }
        ],
        "responses": {
          "200": {
            "description": "Receipt state returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptStateResponse"
                }
              }
            }
          },
          "404": {
            "description": "Receipt not found."
          }
        }
      }
    },
    "/v1/remote-worker/check": {
      "post": {
        "tags": ["Remote Worker TrustPass"],
        "summary": "Create a remote worker readiness receipt",
        "description": "Live module endpoint for consent-bound remote worker readiness receipts. The worker controls consent. The requester owns the request. The company owns the final onboarding decision.",
        "operationId": "checkRemoteWorkerReadiness",
        "security": [
          {
            "PilotKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrustActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Remote worker readiness receipt returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrustActionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload."
          },
          "401": {
            "description": "Missing or invalid pilot key."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PilotKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pilot_key",
        "description": "Scoped pilot key issued by Passpod for selected API scenarios."
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "service": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": ["ok"]
      },
      "TrustActionRequest": {
        "type": "object",
        "properties": {
          "receipt_type": {
            "type": "string",
            "example": "trust_action_receipt"
          },
          "scenario_id": {
            "type": "string",
            "example": "agent_delete"
          },
          "module": {
            "type": "string",
            "example": "AgentTrust Sensitive Action Control"
          },
          "actor": {
            "type": "string",
            "example": "agent-88"
          },
          "subject": {
            "type": "string",
            "example": "production_records"
          },
          "action": {
            "type": "string",
            "example": "delete_production_records"
          },
          "approval": {
            "type": "string",
            "example": "break_glass_approval_required"
          },
          "evidence": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requested_result": {
            "type": "string",
            "example": "BLOCKED"
          },
          "risk_label": {
            "type": "string",
            "example": "Destructive production action"
          },
          "customer_owns_data": {
            "type": "boolean",
            "default": true
          },
          "customer_signs_decision": {
            "type": "boolean",
            "default": true
          },
          "didx_state_only": {
            "type": "boolean",
            "default": true
          }
        },
        "required": [
          "receipt_type",
          "scenario_id",
          "module",
          "actor",
          "subject",
          "action",
          "approval",
          "requested_result"
        ]
      },
      "TrustActionResponse": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string"
          },
          "decision": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "receipt_type": {
            "type": "string"
          },
          "didx_state": {
            "type": "string",
            "enum": ["active", "expired", "revoked", "blocked", "unknown"]
          },
          "revocable": {
            "type": "boolean"
          },
          "customer_decision_owner": {
            "type": "boolean"
          }
        },
        "required": ["receipt_id", "decision", "receipt_type", "didx_state"]
      },
      "ReceiptStateResponse": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": ["active", "expired", "revoked", "blocked", "unknown"]
          },
          "valid": {
            "type": "boolean"
          },
          "didx_state_only": {
            "type": "boolean",
            "default": true
          }
        },
        "required": ["receipt_id", "state", "valid"]
      }
    }
  }
}