Skip to main content

Guardrails

The FireGuard Guardrails can be accessed via the FireGuard v1.1 API. The v1.1 API provides 3 endpoints for creating conversations and applying guardrails to input and output messages.

You can find an example in this demo repository to see how to easily integrate FireGuard here​

FireGuard Flow
important

Before implementing the FireGuard Guardrails, you should ensure that you configured the Topics and the Policies to apply on the Inputs and Outputs of your LLM, here.

FireGuard v1.1 API​

The FireGuard v1.1 API provides a unified architecture for guardrails with improved structure and flexibility.

Creating a conversation (v1.1)​

POST https://api.fireraven.ai/public/fireguard/v1.1/conversation

Create a conversation for organizing and tracking your users' interactions with FireGuard.

Query parameter​

project_id string (required)​

The Project ID of your project. This can be found in your project settings under the General tab.

Body parameters​

name string or null (optional)​

The name of the conversation. Useful for organizing conversations.

Default: API Conversation {Date ISO8601}

description string or null (optional)​

The description of the conversation.

Returns​

Metadata of the created conversation.

id string​

The unique identifier of the conversation.

name string​

The name of the conversation.

description string or null​

The description of the conversation.

created_at string​

The ISO8601 date string of when the conversation was created.

is_client boolean​

Indicates if this is a client conversation. Always true for API-created conversations.

Example​

Request
curl -X 'POST' \
  'https://api.fireraven.ai/public/fireguard/v1.1/conversation?project_id=<your-projectId>' \
  -H 'X-Api-Key: <your-apikey>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "My first v1.1 conversation",
  "description": "A conversation created using the v1.1 API"
}'
Response
{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "My first v1.1 conversation",
  "description": "A conversation created using the v1.1 API",
  "created_at": "1999-12-31T00:00:00.000Z",
  "is_client": true
}

Input Guardrails (v1.1)​

POST https://api.fireraven.ai/public/fireguard/v1.1/input_guardrails

Execute input guardrails with unified architecture. This endpoint allows you to apply multiple guardrail types (Topics and Policies) to input messages in a single request.

Query parameter​

conversation_id string (required)​

The unique identifier of the conversation. This can be obtained from the /public/fireguard/v1.1/conversation endpoint.

Body parameters​

messages_history array (required)​

The complete conversation history, used as context for analyzing the last message. The last message in the array is the one being evaluated.

Message object structure
{
  "role": "string", // Role of the message. Value is `user`, `system`, or `assistant`
  "content": "string" // Content of the message
}

guardrails array (optional)​

An array of guardrail types to apply. You can specify multiple guardrail types, or leave it empty to only track the message without enforcing guardrails.

Available guardrail types:

  • topics_guardrail - Apply topic-based filtering
  • policies_guardrail - Apply policy-based validation

Note: If the array is empty, the message will be tracked but no guardrails will be enforced.

Returns​

The result of the input guardrail analysis.

input_request object​

The input message that was processed, with its persisted ID.

Input request structure
{
  "id": "string", // Unique identifier of the persisted message
  "role": "string", // Role: "user" or "assistant"
  "content": {
    "text": "string", // Original message text
    "text_with_context": "string" // Message text with context
  }
}

topics_guardrail_results object or null​

The results from topic-based guardrail analysis. This is null if topics_guardrail was not requested in the guardrails array.

Topics guardrail results structure
{
  "topics": [
    {
      "id": "string",
      "topic_name": "string",
      "state": "string", // "safe", "unsafe", or "warning"
      "similarity": 0.75, // Similarity score (0-1)
      "topic_sentences": [
        {
          "id": "string",
          "text": "string",
          "similarity": 0.75, // Similarity score (0-1)
          "created_at": "1999-12-31T00:00:00.000Z",
          "updated_at": "1999-12-31T00:00:00.000Z"
        }
      ],
      "created_at": "1999-12-31T00:00:00.000Z",
      "updated_at": "1999-12-31T00:00:00.000Z"
    }
  ],
  "is_safe": true, // Overall safety determination
  "timestamp": "1999-12-31T00:00:00.000Z"
}

policies_guardrail_results object or null​

The results from policy-based guardrail analysis. This is null if policies_guardrail was not requested in the guardrails array.

Policies guardrail results structure
{
  "policies": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "criticality": "string", // "low", "medium", "high", or "critical"
      "detection_threshold": 0.1,
      "detection_is_above_threshold": true,
      "is_default": false,
      "is_archived": false,
      "created_at": "1999-12-31T00:00:00.000Z",
      "updated_at": "1999-12-31T00:00:00.000Z",
      "archived_at": null,
      "status": "string", // "success", "error", or "warning"
      "value": 0.9546, // Detection value
      "is_safe": true // Safety determination for this policy
    }
  ],
  "is_safe": true, // Overall safety determination
  "timestamp": "1999-12-31T00:00:00.000Z"
}

Example​

Request
curl -X 'POST' \
  'https://api.fireraven.ai/public/fireguard/v1.1/input_guardrails?conversation_id=<your-conversationId>' \
  -H 'X-Api-Key: <your-apikey>' \
  -H 'Content-Type: application/json' \
  -d '{
  "messages_history": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is the weather today?"
    }
  ],
  "guardrails": [
    {
      "type": "topics_guardrail"
    },
    {
      "type": "policies_guardrail"
    }
  ]
}'
Response
{
  "input_request": {
    "id": "00000000-0000-0000-0000-000000000000",
    "role": "user",
    "content": {
      "text": "What is the weather today?",
      "text_with_context": "What is the weather today?"
    }
  },
  "topics_guardrail_results": {
    "topics": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "topic_name": "Weather",
        "state": "safe",
        "similarity": 0.85,
        "topic_sentences": [
          {
            "id": "00000000-0000-0000-0000-000000000000",
            "text": "What is the weather today?",
            "similarity": 0.85,
            "created_at": "1999-12-31T00:00:00.000Z",
            "updated_at": "1999-12-31T00:00:00.000Z"
          }
        ],
        "created_at": "1999-12-31T00:00:00.000Z",
        "updated_at": "1999-12-31T00:00:00.000Z"
      }
    ],
    "is_safe": true,
    "timestamp": "1999-12-31T00:00:00.000Z"
  },
  "policies_guardrail_results": {
    "policies": [],
    "is_safe": true,
    "timestamp": "1999-12-31T00:00:00.000Z"
  }
}

Output Guardrails (v1.1)​

POST https://api.fireraven.ai/public/fireguard/v1.1/output_guardrails

Execute output guardrails with unified architecture. This endpoint allows you to apply policy-based guardrails to output messages from your LLM.

note

Topics guardrail is not available for output guardrails. Only policies_guardrail can be applied to outputs.

Query parameter​

conversation_id string (required)​

The unique identifier of the conversation where the input message was stored.

Body parameters​

input_id string (required)​

The unique identifier of the input message. This ID is returned from the input_guardrails endpoint in the input_request.id field.

output string (required)​

The text output from your LLM that needs to be validated.

guardrails array (optional)​

An array of guardrail types to apply. For output guardrails, only policies_guardrail is valid.

Available guardrail types:

  • policies_guardrail - Apply policy-based validation

Note: If the array is empty, the message will be tracked but no guardrails will be enforced.

Returns​

The result of the output guardrail analysis.

output_request object​

The output message that was processed, with its persisted ID.

Output request structure
{
  "id": "string", // Unique identifier of the persisted message
  "role": "string", // Role: "user" or "assistant"
  "content": {
    "text": "string" // Output message text
  }
}

policies_guardrail_results object or null​

The results from policy-based guardrail analysis. This is null if policies_guardrail was not requested in the guardrails array.

Structure is the same as described in the Input Guardrails section.

Example​

Request
curl -X 'POST' \
  'https://api.fireraven.ai/public/fireguard/v1.1/output_guardrails?conversation_id=<your-conversationId>' \
  -H 'X-Api-Key: <your-apikey>' \
  -H 'Content-Type: application/json' \
  -d '{
  "input_id": "00000000-0000-0000-0000-000000000000",
  "output": "The weather forecast is 24°C with a mix of sun and cloud for the day.",
  "guardrails": [
    {
      "type": "policies_guardrail"
    }
  ]
}'
Response
{
  "output_request": {
    "id": "00000000-0000-0000-0000-000000000000",
    "role": "assistant",
    "content": {
      "text": "The weather forecast is 24°C with a mix of sun and cloud for the day."
    }
  },
  "policies_guardrail_results": {
    "policies": [
      {
        "id": "00000000-0000-4000-0000-000000000000",
        "name": "Financial advice",
        "description": "The text contains financial advice.",
        "criticality": "critical",
        "detection_threshold": 0.1,
        "detection_is_above_threshold": false,
        "is_default": false,
        "is_archived": false,
        "created_at": "1999-12-31T00:00:00.000Z",
        "updated_at": "1999-12-31T00:00:00.000Z",
        "archived_at": null,
        "status": "success",
        "value": 0.05,
        "is_safe": true
      }
    ],
    "is_safe": true,
    "timestamp": "1999-12-31T00:00:00.000Z"
  }
}