openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Guardion AI API",
    "summary": "Enterprise-grade guardrails.",
    "description": "Runtime Guardrails & Observability. Guardion AI provides a robust security layer for LLM applications. Use our API to detect prompt injections, PII leakage, and toxic content in real-time. For comprehensive guides and SDKs, visit [docs.guardion.ai](https://docs.guardion.ai).",
    "termsOfService": "https://guardion.ai/terms",
    "contact": {
      "name": "Guardion Support",
      "email": "support@guardion.ai"
    },
    "version": "0.1.2"
  },
  "servers": [
    {
      "url": "https://api.guardion.ai",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/v1/policies": {
      "get": {
        "tags": ["Policy Management"],
        "summary": "List all security policies",
        "description": "Retrieves a collection of active security policies configured for your account.",
        "operationId": "listPolicies",
        "security": [{"HTTPBearer": []}],
        "parameters": [
          {
            "name": "force_refresh",
            "in": "query",
            "required": false,
            "schema": { "type": "boolean", "default": false },
            "description": "Bypass cache and force a fresh fetch of policy data."
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved policy list.",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPolicy-Output" } }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Policy Management"],
        "summary": "Create a new security policy",
        "description": "Defines a new policy with specific detectors (PII, Injection, etc.) and enforcement thresholds.",
        "operationId": "createPolicy",
        "security": [{"HTTPBearer": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/PublicPolicy-Input" } }
          }
        },
        "responses": {
          "200": { "description": "Policy created successfully." }
        }
      }
    },
    "/v1/guard": {
      "post": {
        "tags": ["Protection"],
        "summary": "Evaluate and Protect",
        "description": "The primary entry point for real-time evaluation. Scans messages against your policies and returns a breakdown of violations and a redacted correction choice.",
        "operationId": "guardEvaluate",
        "security": [{"HTTPBearer": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRequest" } }
          }
        },
        "responses": {
          "200": {
            "description": "Evaluation complete. Returns flagged status and corrections.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResponse" } }
            }
          }
        }
      }
    },
    "/v1/detokenize": {
      "post": {
        "tags": ["Data Privacy"],
        "summary": "Reveal Original PII",
        "description": "Inbound process to restore original sensitive data from vaulted tokens (e.g., [CONTACT_HASH]). Requires valid authorization to reveal raw PII.",
        "operationId": "revealPII",
        "security": [{"HTTPBearer": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/DetokenizeRequest" } }
          }
        },
        "responses": {
          "200": {
            "description": "Tokens successfully restored to original values.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/DetokenizeResponse" } }
            }
          }
        }
      }
    },
    "/v1/logs": {
      "get": {
        "tags": ["Observability"],
        "summary": "Fetch Security Logs",
        "description": "Query historical evaluation data, filtered by application, session, or time range for auditing and debugging.",
        "operationId": "getLogs",
        "security": [{"HTTPBearer": []}],
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 100 } },
          { "name": "application", "in": "query", "schema": { "type": "string" }, "description": "Filter logs by specific application ID." },
          { "name": "session", "in": "query", "schema": { "type": "string" }, "description": "Filter logs by unique session ID." }
        ],
        "responses": {
          "200": { "description": "Successfully retrieved logs." }
        }
      }
    },
    "/v1/detectors/{detector_id}": {
      "post": {
        "tags": ["Detectors"],
        "summary": "Run Specific Detector",
        "description": "Executes a standalone check using a specific model (e.g., pii-v0, injection-v1) without running a full policy evaluation.",
        "operationId": "runDetector",
        "parameters": [
          { "name": "detector_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/DetectorRequest" } }
          }
        },
        "responses": {
          "200": { "description": "Detector execution successful." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "HTTPBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Use your Guardion API Key as a Bearer token."
      }
    },
    "schemas": {
      "EvaluationRequest": {
        "type": "object",
        "required": ["messages"],
        "properties": {
          "application": { "type": "string", "description": "The unique ID of the application calling the API." },
          "policy": { "type": "string", "description": "Specific policy ID to enforce. Defaults to application global policy if null." },
          "session": { "type": "string", "description": "A unique identifier to track conversations across multiple turns." },
          "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Messages" } },
          "metadata": { "type": "object", "description": "Key-value pairs for custom filtering in the dashboard." },
          "fail_fast": { "type": "boolean", "default": false, "description": "If true, stops processing and returns immediately after the first policy violation." },
          "breakdown_all": { "type": "boolean", "default": false, "description": "If true, returns details for all detectors, including those that did not flag." }
        }
      },
      "EvaluationResponse": {
        "type": "object",
        "required": ["time", "created", "flagged"],
        "properties": {
          "id": { "type": "string" },
          "time": { "type": "number", "description": "Processing time in milliseconds." },
          "created": { "type": "integer", "description": "Unix timestamp of evaluation." },
          "flagged": { "type": "boolean", "description": "True if any policy violation was detected." },
          "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/Breakdown" } },
          "correction": { "$ref": "#/components/schemas/Correction" }
        }
      },
      "Messages": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": { "type": "string", "enum": ["user", "assistant", "system", "developer"] },
          "content": { "type": "string" }
        }
      },
      "PublicMessages": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": { "type": "string", "enum": ["user", "assistant", "system", "developer"] },
          "content": { "type": "string" }
        }
      },
      "Breakdown": {
        "type": "object",
        "required": ["policy_id", "detector", "detected"],
        "properties": {
          "policy_id": { "type": "string" },
          "detector": { "type": "string" },
          "detected": { "type": "boolean" },
          "threshold": { "type": "number" },
          "score": { "type": "number", "description": "Raw model confidence score." },
          "result": { "type": "array", "items": { "type": "object" }, "description": "Detailed evidence of findings (spans, labels, etc)." }
        }
      },
      "Correction": {
        "type": "object",
        "required": ["choices"],
        "properties": {
          "choices": { "type": "array", "items": { "$ref": "#/components/schemas/Messages" }, "description": "The recommended safe version of the input/output messages." }
        }
      },
      "DetokenizeRequest": {
        "type": "object",
        "required": ["messages"],
        "properties": {
          "messages": { "type": "array", "items": { "$ref": "#/components/schemas/PublicMessages" } },
          "application": { "type": "string" },
          "policy": { "type": "string" }
        }
      },
      "DetokenizeResponse": {
        "type": "object",
        "required": ["messages"],
        "properties": {
          "messages": { "type": "array", "items": { "$ref": "#/components/schemas/PublicMessages" } }
        }
      },
      "PublicPolicy-Input": {
        "type": "object",
        "required": ["id"],
        "properties": {
          "id": { "type": "string" },
          "definition": { "type": "string" },
          "threshold": { "type": "number", "default": 0.8 },
          "detectors": { "type": "array", "items": { "$ref": "#/components/schemas/PublicDetector" } }
        }
      },
      "PublicPolicy-Output": {
        "type": "object",
        "required": ["id"],
        "properties": {
          "id": { "type": "string" },
          "definition": { "type": "string" },
          "threshold": { "type": "number" },
          "detectors": { "type": "array", "items": { "$ref": "#/components/schemas/PublicDetector" } }
        }
      },
      "PublicDetector": {
        "type": "object",
        "required": ["model"],
        "properties": {
          "model": { "type": "string", "description": "The detector model to use (e.g., pii-v0, injection-v1)." },
          "target": { "type": "string", "enum": ["user", "assistant", "system", "all"] }
        }
      }
    }
  }
}