Skip to main content

AI Guard APIs

Once enabled, AI Guard is accessible via its APIs.

tip

You can explore the service APIs, try parameters, and inspect responses using our fully interactive API Reference for AI Guard and other Pangea services.

Making a request​

Use the /v1/text/guard endpoint to call AI Guard APIs.

For example:

Set environment variables
export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_AI_GUARD_TOKEN="pts_qjrtzl...th64rk"
POST /v1/text/guard
curl --location "https://ai-guard.$PANGEA_DOMAIN/v1/text/guard" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $PANGEA_AI_GUARD_TOKEN" \
--data '{
  "text": "Hi, I need help with my bank application. Here’s my SSN: 234-56-7890. Please let me know if you need anything else!"
}'
/v1/text/guard response
{
  "status": "Success",
  "summary": "Prompt Injection was not detected.  Confidential and PII was detected and reported.  Malicious Entity was not detected.",
  "result": {
    "recipe": "pangea_prompt_guard",
    "blocked": false,
    "prompt_text": "Hi, I need help with my bank application. Here’s my SSN: *******7890. Please let me know if you need anything else!",
    "detectors": {
      "prompt_injection": {
        "detected": false,
        "data": null
      },
      "pii_entity": {
        "detected": true,
        "data": {
          "entities": [
            {
              "type": "US_SSN",
              "value": "234-56-7890",
              "action": "redacted:replaced"
            }
          ]
        }
      },
      "malicious_entity": {
        "detected": false,
        "data": null
      }
    }
  }
}

Required parameters​

text or messages​

You can submit text for analysis using one of the following parameters:

  • text - Provide simple, unstructured text, such as a user question or an individual message.

    For example:

    /v1/text/guard payload
    --data '{
      "text": "My SSN is 234-56-7890; what do you have on me?",
    }'

  • messages - Alternatively, you can provide an array of messages in JSON format, following well-known schemas from major AI providers.

    These messages may include user and system prompts, tool and LLM responses, or the agent state. For example:

    /v1/text/guard payload
    --data '{
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful assistant."
        },
        {
          "role": "user",
          "content": "Here's my corporate credit card: 4111 1111 1111 1111. Buy me something."
        }
      ]
    }'

Specifying multiple input parameters in a request will result in a validation error. There can be only one.

tip

The current version of AI Guard supports processing up to 20 KiB of text.

Optional parameters​

recipe​

To accommodate different security requirements at various stages of your AI-powered application flow, AI Guard supports multiple configurations called recipes. When making a request, you can specify which recipe to apply using the recipe parameter.

If you don't specify a recipe, the default pangea_prompt_guard recipe is applied.

Several out-of-the-box recipes are included in the default service configuration, optimized for common use cases:

  • pangea_prompt_guard - Processing user prompts
  • pangea_ingestion_guard - Analyzing RAG ingestion data
  • pangea_llm_prompt_guard - Validating final prompts submitted to an LLM
  • pangea_llm_response_guard - Filtering and sanitizing responses received from the LLM
  • pangea_agent_pre_plan_guard - Ensuring agent planning integrity
  • pangea_agent_pre_tool_guard - Safeguarding tool input parameters
  • pangea_agent_post_tool_guard - Verifying agent and tool outputs

For example:

/v1/text/guard payload
--data '{
  ...
  "recipe": "pangea_ingestion_guard"
}'

You can create an unlimited number of custom recipes using available detectors or modify existing recipes to fit your needs.

debug​

Setting the debug parameter to true will include additional details about malicious detections under the raw key in the API response. This information may include the detection category, a relative confidence score, and the final verdict.

For example:

/v1/text/guard payload
--data '{
  ...
  "debug": true
}'

overrides​

AI Guard allows you to specify the action to take when a detector (such as Prompt Guard) or an individual detector component (such as an IP address within the Malicious Entity detector) identifies a threat.

Using the overrides parameter, you can modify this action for each detector or detector component in an individual API request.

Additionally, overrides allow you to disable specific detectors or their components within a recipe by setting the disabled attribute to true. Setting disabled to false does not affect the detector.

Unless explicitly overridden or disabled, the settings of the specified recipe remain in effect.

This makes the service fully API-driven and independent of the configuration saved in your Pangea User Console, serving as a useful default.

The overrides parameter consists of detector objects and detector-specific components. For example:

/v1/text/guard payload
--data '{
  ...
  "overrides": {
    "pii_entity": {
      "us_ssn": "fpe"
    }
  }
}'

You can find the supported detectors and component parameters in the interactive API Reference for AI Guard.

log_fields​

The log_fields parameter helps enhance the context of activity logs by including customizable metadata in your AI Guard Activity Log . This can be useful for tracking, auditing, or analyzing specific activities. The available fields are:

  • citations - Origin or source application of the event, such as Slack, GDrive, Confluence.
  • extra_info - Additional supplementary details related to the event.
  • model - The model used.
  • source - The IP address of the user, app, or agent that triggered the event.
  • tools - Specifies the tools used in the request, such as search-tool or custom-retriever.

For example:

/v1/text/guard payload
--data '{
  ...
  "log_fields": {
    "citations": "ai-app",
    "extra_info": "Confidential documents retrieved.",
    "model": "gpt-4o-mini",
    "source": "555.555.555.555",
    "tools": "custom-retriever"
  }
}'

Understanding responses​

The service returns the following:

  • Processed text or JSON
  • Applied recipe
  • Summary of actions taken
  • List of detectors used
  • Details of detections made
  • Input modifications
  • Whether the request was blocked

Based on this information, your application can decide whether to pass the processed content to the next recipient - an LLM, an agent, a (vector) store, the user, etc.:

Attributes​

summary​

The summary value lists the enabled detectors and describes the action taken and the outcome for each. If a detector blocks execution, subsequent detectors are not applied. For example:

/v1/text/guard response
{
  ...
  "status": "Success",
  "summary": "Prompt Injection was detected and blocked. Malicious Entity was not executed.",
  "result": {
    ...
  }
}

result​

The result attribute provides details about the outcome of the call and the processed (guarded) text through the following keys:

recipe​

The recipe attribute returns the recipe specified in the request or the default recipe applied. For example:

/v1/text/guard response
{
  ...
  "result": {
    "recipe": "pangea_prompt_guard",
    ...
  }
}
blocked​

The blocked attribute can be either true or false and indicates whether the execution was stopped by a detector at any point. Combined with the detectors attribute (described below), this helps you understand why certain detectors may not have been executed. If execution is not blocked, all detectors in the specified recipe are applied. For example:

/v1/text/guard response
{
  ...
  "summary": "Prompt Injection was not detected.  Confidential and PII was detected and reported.  Malicious Entity was not detected.",
  "result": {
    ...
    "blocked": false,
    ...
  }
}

A "blocked": true value indicates that your application should not proceed with the request.

prompt_text or prompt_messages​

  • text - If you specify the text parameter, the guarded text will be returned in the prompt_text attribute. For example:

    /v1/text/guard response
    {
      ...
      "result": {
        ...
        "prompt_text": "Take my SSN: *******7890!",
        ...
      }
    }

  • messages - When you specify the messages parameter and provide a valid JSON structure that conforms to a recognized schema from a major AI provider, the result will include the original JSON with the processed content in the prompt_messages attribute. For example:

    /v1/text/guard response
    {
      ...
      "result": {
        ...
        "prompt_messages": [
          {
            "role": "system",
            "content": "You are a helpful assistant."
          },
          {
            "role": "user",
            "content": "Here's my corporate credit card: <CREDIT_CARD>. Buy me something."
          }
        ],
        ...
      }
    }

    or

    /v1/text/guard response
    {
      ...
      "result": {
        ...
        "prompt_messages": {
          "model": "gpt-4o",
          "messages": [
            {
              "role": "system",
              "content": "You are a helpful assistant."
            },
            {
              "role": "user",
              "content": "Here's my corporate credit card: <CREDIT_CARD>. Buy me something."
            }
          ]
        },
        ...
      }
    }

    If the input does not match a recognized schema, it will be processed as text and returned in the prompt_text attribute.

detectors​

The detectors attribute returns a set of detectors in the order they were applied. For each detector, the report may include:

  • Whether a detection was made
  • Type of detection
  • Analyzer used and the confidence score (between 0.00 and 1.00) when a prompt injection is detected
  • Action taken
  • Detected value
  • Modified value

For example:

/v1/text/guard response
{
  ...
  "result": {
    ...
    "detectors": {
      "prompt_injection": {
        "detected": true,
        "data": {
          "action": "reported",
          "analyzer_responses": [
            {
              "analyzer": "PA1003",
              "confidence": 1
            }
          ]
        }
      },
      "pii_entity": {
        "detected": true,
        "data": {
          "entities": [
            {
              "type": "EMAIL_ADDRESS",
              "value": "test@example.com",
              "action": "redacted",
              "start_pos": 40,
              "redacted_value": "************.com"
            },
            {
              "type": "IP_ADDRESS",
              "value": "190.28.74.251",
              "action": "redacted:encrypted",
              "start_pos": 79,
              "redacted_value": "467.98.88.357"
            }
          ]
        }
      },
      "profanity_and_toxicity": {
        "detected": false,
        "data": null
      }
    },
  }
}
fpe_context​

If a detector component redacts a sensitive value using Format-Preserving Encryption (FPE), the response includes the fpe_context attribute, which is used to decrypt the value.

/v1/text/guard response
  ...
  "result": {
    ...
    "prompt_text": "Take my SSN: 631-73-4356!",
    ...
    "fpe_context": "eyJhIjogIkFFUy1GRjMtMS0yNTYtQkVUQSIsICJtIjogW3siYSI6IDEsICJzIjogMTMsICJlIjogMjQsICJ0IjogIlVTX1NTTiIsICJ2IjogIjYzMS03My00MzU2In1dLCAidCI6ICJQbWg1VWJ5IiwgImsiOiAicHZpXzYzZDJ0M21rc2plY2ZlbDVoaG0yaDJ0eHJzb3h0eTJkIiwgInYiOiAxLCAiYyI6ICJwY2lfcmEzY2VycHlkajJ2YnZ2dm1qdml1a2s2Nm5lZHk3M2EifQ=="
}
note

You can use the /v1/unredact endpoint to retrieve the original value using the encrypted data and the returned FPE context:

curl -sSLX POST 'https://redact.aws.us.pangea.cloud/v1/unredact' \
-H 'Authorization: Bearer pts_br2suu...hrbway6' \
-H 'Content-Type: application/json' \
-d '{"config_id":"pci_kvef6aetpeozuphbpewye2rapvtjh577","fpe_context":"eyJhIjogIkFFUy1GRjMtMS0yNTYtQkVUQSIsICJtIjogW3siYSI6IDEsICJzIjogMTMsICJlIjogMjQsICJ0IjogIlVTX1NTTiIsICJ2IjogIjYzMS03My00MzU2In1dLCAidCI6ICJQbWg1VWJ5IiwgImsiOiAicHZpXzYzZDJ0M21rc2plY2ZlbDVoaG0yaDJ0eHJzb3h0eTJkIiwgInYiOiAxLCAiYyI6ICJwY2lfcmEzY2VycHlkajJ2YnZ2dm1qdml1a2s2Nm5lZHk3M2EifQ==","redacted_data":"631-73-4356"}'
{
  ...
  "result": {
    "data": "234-56-7890"
  }
}

See additional details in the Redact documentation

Was this article helpful?

Contact us