Scan streaming

AI GUARDRAILS

This article is meant for AI Guardrails users.

ROLES AND PERMISSIONS

To complete the task described in this section, make sure you have the required permissions.

• Learn more about permissions in AI Security

Overview

The /backend/v1/scans/raw/{format} endpoint scans streaming request and response bodies through F5 AI Guardrails. This works with OpenAI response formats. You send the body to AI Security, AI Guardrails scans run on the content, and the endpoint returns the same content back. Scan results come back as response headers.

This is useful when you call a third-party API directly and want to run AI Guardrails on the content before or after the call, without routing traffic through the provider-compatible endpoints.

SUPPORTED FORMATS

This endpoint currently supports OpenAI Responses API formats.

• Learn more about prompts and scans
• Learn more about streaming support

Before you begin

Before you begin, make sure you have:

• An AI Security token: A valid bearer token for authenticating with the AI Security API. Learn more about permissions and tokens.
• A project with guardrails: At least one project with guardrails turned on. Learn how to create a project.
• Your AI Security hostname: Replace <AI_SECURITY_HOSTNAME> in the examples with the hostname for your AI Security deployment.

---

How it works

When you send a request to the /backend/v1/scans/raw/{format} endpoint, it:

1. Accepts a raw request body or server-sent event (SSE) stream body that you provide.
2. Runs all configured guardrail scanners on the content.
3. Returns the same content back, preserving the original chunks for streamed bodies.
4. Communicates scan results through response headers.

The endpoint doesn't call any upstream AI provider. You keep full control over when and how you interact with the provider.

Format values

The {format} path parameter specifies how AI Security interprets the body you send:

• openai-responses-request -- Interprets the body as a JSON request for the OpenAI Responses API. Use this format to scan outgoing request bodies before you send them to OpenAI.
• openai-responses-sse -- Interprets the body as a captured SSE stream from the OpenAI Responses API. AI Security reassembles the stream content and scans it. Use this format to scan incoming streamed responses after you receive them from OpenAI.

Response headers

The endpoint returns the following headers with every response:

• x-ai-security-outcome -- The scan outcome (for example, cleared). This header indicates whether the content passed all configured guardrails.
• x-ai-security-scan-id -- A UUID that identifies the scan. Use this value to look up scan details in audit logs or the AI Security dashboard.
• x-ai-security-error -- Included only when an error occurs during scanning. Contains a message that describes what went wrong.

---

Scan a request body before you send it

Use the openai-responses-request format to scan a raw JSON request body before you send it to the OpenAI Responses API.

To scan a request body:

1. Send the raw JSON request body to the scan endpoint:

   curl -X POST \
     -H "Authorization: Bearer <YOUR_API_TOKEN>" \
     -H "Content-Type: application/json" \
     "https://<AI_SECURITY_HOSTNAME>/backend/v1/scans/raw/openai-responses-request" \
     -d '{
       "model": "gpt-5-nano",
       "input": "My credit card number is 4111-1111-1111-1111 and my SSN is 123-45-6789. Help me fill out this form.",
       "stream": true
     }'

2. Check the response headers for the scan result.

   A successful scan returns headers like the following:

   HTTP/2 200
   x-ai-security-outcome: cleared
   x-ai-security-scan-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

3. Analyze the outcome.

   • If x-ai-security-outcome is cleared, the content passed all guardrails. You can safely send it to the provider.
   • If the outcome indicates a violation, take action based on your application logic. For example, block the request or alert the user.

   The response body is the same request JSON that you sent.

---

Scan an SSE stream response after you receive it

Use the openai-responses-sse format to scan a captured SSE stream response from the OpenAI Responses API. This format runs guardrails on the full streamed response after you receive it from OpenAI.

To scan an SSE stream response:

1. Pipe the OpenAI Responses API output directly into the AI Security scan endpoint:

   curl https://api.openai.com/v1/responses \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <YOUR_OPENAI_API_KEY>" \
     -d '{
       "model": "gpt-5-nano",
       "input": "My credit card number is 4111-1111-1111-1111 and my SSN is 123-45-6789. Help me fill out this form.",
       "stream": true
     }' | curl -X POST \
       -H "Authorization: Bearer <YOUR_API_TOKEN>" \
       "https://<AI_SECURITY_HOSTNAME>/backend/v1/scans/raw/openai-responses-sse" \
       --data-binary @-

   This command sends a streaming request to the OpenAI Responses API. It pipes the complete SSE stream directly into AI Security for scanning.

2. Check the response headers for the scan result.

   A successful scan returns headers like the following:

   HTTP/2 200
   x-ai-security-outcome: cleared
   x-ai-security-scan-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

3. Analyze the outcome.

   • If x-ai-security-outcome is cleared, the streamed response passed all guardrails. You can safely use it in your application.
   • If the outcome indicates a violation, take action based on your application logic.

RESPONSE BODY

The response body contains the same SSE chunks that you sent. The stream contains events like response.created, response.in_progress, and response.completed, following the event structure of the OpenAI Responses API.

---

References

For more information, see:

• Prompts and scans in AI Security
• Streaming for AI Guardrails
• Send a guardrail request to a specific project
• OpenAI compatibility