{
  "openapi": "3.1.0",
  "info": {
    "title": "TrustLoop Governance API",
    "description": "AI agent governance for Custom GPTs and any AI agent. Intercept tool calls, enforce governance rules, block dangerous actions, and maintain a tamper-proof audit trail.\n\nGet your free API key at https://trustloop.live/signup",
    "version": "1.0.0",
    "contact": {
      "name": "TrustLoop",
      "url": "https://trustloop.live",
      "email": "hello@trustloop.live"
    }
  },
  "servers": [
    {
      "url": "https://api.trustloop.live",
      "description": "TrustLoop production API"
    }
  ],
  "paths": {
    "/api/intercept": {
      "post": {
        "operationId": "interceptToolCall",
        "summary": "Intercept a tool call for governance check",
        "description": "Call this before executing any sensitive action — sending emails, accessing databases, making API calls, transferring data, modifying files, or any operation that affects external systems. TrustLoop evaluates the call against your organisation's governance rules and returns an immediate decision.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tool_name"],
                "properties": {
                  "tool_name": {
                    "type": "string",
                    "description": "The name of the action or tool being called. Use descriptive names like 'send_email', 'delete_record', 'transfer_funds', 'post_to_slack'.",
                    "examples": ["send_email", "delete_database_record", "transfer_funds", "access_customer_data"]
                  },
                  "arguments": {
                    "type": "object",
                    "description": "The parameters being passed to the tool. Include all relevant details — TrustLoop uses these to evaluate risk.",
                    "examples": [
                      {"to": "ceo@company.com", "subject": "Contract", "body": "Please sign..."},
                      {"table": "customers", "where": {"id": 123}},
                      {"amount": 50000, "currency": "GBP", "to_account": "GB29NWBK..."}
                    ]
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "Name of the agent or GPT making this call. Used for per-agent tracking in the dashboard. Set to your GPT's name.",
                    "examples": ["customer-support-gpt", "finance-assistant", "hr-copilot"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Governance decision returned. Check the `allowed` field before proceeding.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "allowed": {
                      "type": "boolean",
                      "description": "If true, the action is permitted and you may proceed. If false, do NOT execute the action."
                    },
                    "status": {
                      "type": "string",
                      "enum": ["ALLOWED", "BLOCKED", "PENDING"],
                      "description": "ALLOWED: proceed. BLOCKED: action denied by governance rule or kill-switch. PENDING: awaiting human approval — do not proceed until approved."
                    },
                    "message": {
                      "type": "string",
                      "description": "Human-readable explanation of the decision. Share this with the user when blocked."
                    },
                    "call_id": {
                      "type": "string",
                      "description": "Unique ID for this intercept event. Reference this in support queries."
                    },
                    "approval_id": {
                      "type": "string",
                      "description": "Present when status is PENDING. The approver has been notified by email. Poll or wait for approval before proceeding."
                    },
                    "risk_score": {
                      "type": "number",
                      "description": "Risk score from 0 (low) to 1 (high) assigned by TrustLoop's AI risk engine."
                    }
                  }
                },
                "examples": {
                  "allowed": {
                    "value": {
                      "allowed": true,
                      "status": "ALLOWED",
                      "call_id": "c_01HXYZ123",
                      "risk_score": 0.12
                    }
                  },
                  "blocked": {
                    "value": {
                      "allowed": false,
                      "status": "BLOCKED",
                      "message": "Blocked by rule: delete operations on customer data require human approval",
                      "call_id": "c_01HXYZ456",
                      "risk_score": 0.91
                    }
                  },
                  "pending": {
                    "value": {
                      "allowed": false,
                      "status": "PENDING",
                      "message": "This action requires approval from your administrator. They have been notified by email.",
                      "call_id": "c_01HXYZ789",
                      "approval_id": "ap_01HXYZ789",
                      "risk_score": 0.74
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key. Check your x-api-key header.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": {
            "description": "Monthly call limit reached for your plan. Upgrade at app.trustloop.live.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        },
        "security": [{ "ApiKeyAuth": [] }]
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Get governance stats for your account",
        "description": "Returns total tool calls, blocked count, pending approvals, and agent breakdown for the current month.",
        "responses": {
          "200": {
            "description": "Stats returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": { "type": "integer", "description": "Total tool calls this month" },
                    "allowed": { "type": "integer" },
                    "blocked": { "type": "integer" },
                    "pending": { "type": "integer" },
                    "agents": {
                      "type": "object",
                      "properties": {
                        "used": { "type": "integer" },
                        "limit": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [{ "ApiKeyAuth": [] }]
      }
    },
    "/api/blocked-tools": {
      "get": {
        "operationId": "getBlockedTools",
        "summary": "List all tools on the kill-switch",
        "description": "Returns all tools that are currently blocked for your account. Any intercept call for these tools will be immediately rejected.",
        "responses": {
          "200": {
            "description": "List of blocked tools.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "tool_name": { "type": "string" },
                      "reason": { "type": "string" },
                      "agent_name": { "type": "string", "description": "null = blocked for all agents" },
                      "created_at": { "type": "string", "format": "date-time" }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [{ "ApiKeyAuth": [] }]
      },
      "post": {
        "operationId": "blockTool",
        "summary": "Instantly block a tool (kill-switch)",
        "description": "Immediately blocks a tool across all agents. All future intercept calls for this tool will be rejected until unblocked.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tool_name"],
                "properties": {
                  "tool_name": { "type": "string", "description": "The tool name to block." },
                  "reason": { "type": "string", "description": "Why this tool is being blocked. Stored in audit trail." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool blocked successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool_name": { "type": "string" }
                  }
                }
              }
            }
          }
        },
        "security": [{ "ApiKeyAuth": [] }]
      }
    },
    "/api/approval-rules": {
      "get": {
        "operationId": "getRules",
        "summary": "List all governance rules",
        "description": "Returns all AI-evaluated governance rules for your account written in plain English.",
        "responses": {
          "200": {
            "description": "List of rules.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "rule_text": { "type": "string" },
                      "action": { "type": "string", "enum": ["approve", "block"] },
                      "created_at": { "type": "string", "format": "date-time" }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [{ "ApiKeyAuth": [] }]
      }
    },
    "/api/logs": {
      "get": {
        "operationId": "getAuditLogs",
        "summary": "Get the audit log of all tool calls",
        "description": "Returns recent tool call records — what your agents tried to do, when, and what TrustLoop decided. Filter by status, tool name, or agent.",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Max records to return (default 50, max 200)" },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["ALLOWED", "BLOCKED", "PENDING", "APPROVED", "DENIED"] }, "description": "Filter by decision status" },
          { "name": "tool_name", "in": "query", "schema": { "type": "string" }, "description": "Filter by tool name" },
          { "name": "agent_name", "in": "query", "schema": { "type": "string" }, "description": "Filter by agent name" }
        ],
        "responses": {
          "200": {
            "description": "Audit log entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "tool_name": { "type": "string" },
                      "agent_name": { "type": "string" },
                      "status": { "type": "string", "enum": ["ALLOWED", "BLOCKED", "PENDING", "APPROVED", "DENIED"] },
                      "risk_score": { "type": "number" },
                      "message": { "type": "string" },
                      "created_at": { "type": "string", "format": "date-time" }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [{ "ApiKeyAuth": [] }]
      }
    },
    "/api/pending-approvals": {
      "get": {
        "operationId": "getPendingApprovals",
        "summary": "List tool calls awaiting human approval",
        "description": "Returns all tool calls that are currently in PENDING status, waiting for a human to approve or deny them.",
        "responses": {
          "200": {
            "description": "Pending approvals.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "tool_name": { "type": "string" },
                      "agent_name": { "type": "string" },
                      "arguments": { "type": "object" },
                      "created_at": { "type": "string", "format": "date-time" }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [{ "ApiKeyAuth": [] }]
      }
    },
    "/api/pending-approvals/{id}/decide": {
      "post": {
        "operationId": "decideApproval",
        "summary": "Approve or deny a pending tool call",
        "description": "Approve or deny a specific tool call that is waiting for human decision.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The pending approval ID" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["action"],
                "properties": {
                  "action": { "type": "string", "enum": ["approved", "denied"], "description": "Whether to approve or deny this tool call." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decision recorded.",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string" } } }
              }
            }
          }
        },
        "security": [{ "ApiKeyAuth": [] }]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your TrustLoop API key. Get one free at https://trustloop.live/signup"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Human-readable error message." }
        }
      }
    }
  }
}