{
  "swagger": "2.0",
  "info": {
    "title": "Fireraven Guardrails API",
    "description": "Check user input and AI output against policies and security guardrails. Use these endpoints from Copilot Studio to validate messages before or after your agent responds.",
    "version": "1.0.0"
  },
  "host": "api.fireraven.ai",
  "basePath": "/public/fireguard/v1",
  "schemes": ["https"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "securityDefinitions": {
    "ApiKeyAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "x-api-key",
      "description": "Your Fireraven API key from Organization Settings > API Keys"
    }
  },
  "security": [{ "ApiKeyAuth": [] }],
  "definitions": {
    "InputGuardrailsBody": {
      "type": "object",
      "required": ["messages_history", "guardrails"],
      "properties": {
        "messages_history": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "role": { "type": "string" },
              "content": { "type": "string" }
            }
          }
        },
        "guardrails": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": { "type": { "type": "string" } }
          }
        }
      }
    },
    "OutputGuardrailsBody": {
      "type": "object",
      "required": ["input_id", "output", "guardrails"],
      "properties": {
        "input_id": { "type": "string" },
        "output": { "type": "string" },
        "guardrails": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": { "type": { "type": "string" } }
          }
        }
      }
    },
    "CreateConversationBody": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "description": { "type": "string" }
      }
    }
  },
  "paths": {
    "/input_guardrails": {
      "post": {
        "consumes": ["application/json"],
        "produces": ["application/json"],
        "operationId": "inputGuardrails",
        "summary": "Check user input for policy or security violations",
        "description": "Validates the latest user message and conversation history against your organization policies and security guardrails. Call this before processing user input in your agent.",
        "parameters": [
          {
            "name": "conversation_id",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "The Fireraven conversation ID for this chat thread."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": { "$ref": "#/definitions/InputGuardrailsBody" }
          }
        ],
        "responses": {
          "200": { "description": "Guardrail result for the input." }
        }
      }
    },
    "/output_guardrails": {
      "post": {
        "consumes": ["application/json"],
        "produces": ["application/json"],
        "operationId": "outputGuardrails",
        "summary": "Validate AI response before sending to user",
        "description": "Checks the agent response text against policies and security guardrails. Call this before returning the reply to the user. Requires the input_id from the corresponding input_guardrails call.",
        "parameters": [
          {
            "name": "conversation_id",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "The Fireraven conversation ID for this chat thread."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": { "$ref": "#/definitions/OutputGuardrailsBody" }
          }
        ],
        "responses": {
          "200": { "description": "Guardrail result for the output." }
        }
      }
    },
    "/conversation_copilot": {
      "post": {
        "consumes": ["application/json"],
        "produces": ["application/json"],
        "operationId": "createConversationCopilot",
        "summary": "Create or reuse a Fireraven conversation for a Copilot Studio conversation",
        "description": "Maps a Copilot Studio conversation to a Fireraven conversation. If a mapping already exists for the given Copilot conversation id, the existing Fireraven conversation is returned. Otherwise a new conversation is created and mapped.",
        "parameters": [
          {
            "name": "project_id",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "The Fireraven project (chatbot) ID."
          },
          {
            "name": "conversation_copilot_id",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "The Copilot Studio conversation ID to map."
          },
          {
            "name": "body",
            "in": "body",
            "schema": { "$ref": "#/definitions/CreateConversationBody" }
          }
        ],
        "responses": {
          "200": { "description": "Existing or created conversation with id." }
        }
      }
    }
  }
}