> For the complete documentation index, see [llms.txt](https://ai-security-docs.akto.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-security-docs.akto.io/agentic-guardrails/overview/guardrails-api.md).

# Guardrails as API

Use the Akto Guardrails HTTP API to inspect and ingest AI agent traffic directly

## Overview

Akto exposes its guardrail engine as a standalone HTTP API. Any application or agent can send request/response traffic to this endpoint directly, no SDK, proxy sidecar, or framework hook required. Akto evaluates the payload against your configured guardrail policies, ingests the interaction into the Akto dashboard, and returns a verdict.

Use this connector when:

* You are building a homegrown AI agent and cannot install a framework-specific hook
* You want to evaluate guardrails inline from any language or runtime
* You are integrating from a system where installing dependencies is not practical (e.g. serverless functions, edge runtimes, shell scripts)

**What Akto does with each request:**

* Evaluates the request payload against input guardrails (prompt injection, PII, policy violations)
* Evaluates the response payload against output guardrails (sensitive data leakage, unsafe outputs)
* Ingests the full interaction into the Akto dashboard under a collection named after the target host
* Returns a guardrail verdict so callers can block or allow the request in real time

## Prerequisites

Before you start, you need:

* An **Akto API token**: follow the [Getting API Token](/akto-argus-agentic-ai-security-for-homegrown-ai/connectors/others/hybrid-saas.md#getting-api-token) steps in the Hybrid SaaS guide
* Your **Guardrails Service URL**: contact the Akto support team to get the URL for your account. It follows the format `https://<account_id>-guardrails.akto.io`

## API Reference

### Endpoint

```
POST https://<GUARDRAILS_SERVICE_URL>/api/http-proxy
```

### Query Parameters

All three parameters are required:

<table><thead><tr><th width="225.015625">Parameter</th><th width="114.375">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>guardrails</code></td><td><code>true</code></td><td>Run guardrail checks on the request payload</td></tr><tr><td><code>response_guardrails</code></td><td><code>true</code></td><td>Run guardrail checks on the response payload</td></tr><tr><td><code>ingest_data</code></td><td><code>true</code></td><td>Send the interaction to the Akto dashboard for monitoring and visibility</td></tr></tbody></table>

### Headers

<table><thead><tr><th width="218.23046875">Header</th><th width="187.65234375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>authorization</code></td><td>Yes</td><td>Your Akto API token</td></tr><tr><td><code>Content-Type</code></td><td>Yes</td><td><code>application/json</code></td></tr></tbody></table>

### Request Body

The body represents one HTTP interaction (a request/response pair from your AI agent). All fields are required.

```json
{
  "path": "/v1/messages",
  "requestHeaders": "{\"host\":\"your-agent.example.com\"}",
  "responseHeaders": "{}",
  "method": "POST",
  "requestPayload": "{\"body\":\"<prompt or message sent to the LLM>\"}",
  "responsePayload": "{\"body\":\"<response received from the LLM>\"}",
  "ip": "127.0.0.1",
  "time": "1780531200000",
  "statusCode": "200",
  "type": null,
  "status": "200",
  "akto_account_id": "1000000",
  "akto_vxlan_id": "0",
  "is_pending": "false",
  "source": "MIRRORING",
  "tag": "{\"gen-ai\":\"Gen AI\",\"source\":\"AGENTIC\"}",
  "contextSource": "AGENTIC"
}
```

#### Field Reference

{% hint style="warning" %}

## **All fields are mandatory.**

Every field listed below must be included in the request body, even the ones with a fixed or default value (e.g. `type`, `akto_vxlan_id`, `is_pending`).
{% endhint %}

<table><thead><tr><th width="200.21875">Field</th><th width="198.09765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>string</td><td>The API path of the upstream call (e.g. <code>/v1/messages</code>, <code>/v1/chat/completions</code>)</td></tr><tr><td><code>requestHeaders</code></td><td>stringified JSON</td><td>Headers sent with the request. The <code>host</code> value becomes the <strong>collection name</strong> in Akto</td></tr><tr><td><code>responseHeaders</code></td><td>stringified JSON</td><td>Headers received with the response. Pass <code>"{}"</code> if not available</td></tr><tr><td><code>method</code></td><td>string</td><td>HTTP method of the upstream call (e.g. <code>POST</code>, <code>GET</code>)</td></tr><tr><td><code>requestPayload</code></td><td>stringified JSON</td><td>Body of the request sent to the LLM or agent. Use <code>{"body": "&#x3C;content>"}</code> format</td></tr><tr><td><code>responsePayload</code></td><td>stringified JSON</td><td>Body of the response received from the LLM or agent. Use <code>{"body": "&#x3C;content>"}</code> format</td></tr><tr><td><code>ip</code></td><td>string</td><td>IP address of the caller. Use <code>"127.0.0.1"</code> if not applicable</td></tr><tr><td><code>time</code></td><td>string</td><td>Unix timestamp in <strong>milliseconds</strong> of when the interaction occurred</td></tr><tr><td><code>statusCode</code></td><td>string</td><td>HTTP status code of the upstream response (e.g. <code>"200"</code>, <code>"500"</code>)</td></tr><tr><td><code>type</code></td><td>string or null</td><td>Set to <code>null</code> unless instructed otherwise</td></tr><tr><td><code>status</code></td><td>string</td><td>Same as <code>statusCode</code></td></tr><tr><td><code>akto_account_id</code></td><td>string</td><td>Your Akto account ID. Use <code>"1000000"</code> unless the Akto support team specifies otherwise</td></tr><tr><td><code>akto_vxlan_id</code></td><td>string</td><td>Set to <code>"0"</code> unless instructed otherwise</td></tr><tr><td><code>is_pending</code></td><td>string</td><td>Set to <code>"false"</code></td></tr><tr><td><code>source</code></td><td>string</td><td>Traffic source label. Use <code>"MIRRORING"</code> for agentic traffic</td></tr><tr><td><code>tag</code></td><td>stringified JSON</td><td>Labels attached to the interaction. The <code>source</code> key inside the tag must match the product: <code>"AGENTIC"</code> for Akto Argus</td></tr><tr><td><code>contextSource</code></td><td>string</td><td>Identifies the product context: <code>"AGENTIC"</code> for Akto Argus (homegrown AI</td></tr></tbody></table>

{% hint style="info" %}
**Collection Naming**

The `host` value inside `requestHeaders` determines which collection this interaction appears under in the Akto dashboard. Use a consistent, descriptive hostname (e.g. `"my-agent.internal"`) to group traffic from the same agent together.
{% endhint %}

## File / Media Validation API

Use this endpoint when the payload is a file (image, video, audio, PDF, etc.) rather than a JSON body. The endpoint accepts a `multipart/form-data` request and evaluates the file against your configured guardrail policies.

### Endpoint

```
POST https://<GUARDRAILS_SERVICE_URL>/api/validate/file
```

### Headers

<table><thead><tr><th width="218">Header</th><th width="140">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Your Akto API token</td></tr></tbody></table>

### Form Fields

All fields are sent as `multipart/form-data` parts:

<table><thead><tr><th width="200">Field</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>file</code></td><td>Yes</td><td>The file to validate (binary upload)</td></tr><tr><td><code>contextSource</code></td><td>Yes</td><td>Product context. Use <code>"ENDPOINT"</code> for Akto Atlas</td></tr><tr><td><code>path</code></td><td>Yes</td><td>API path where the file was submitted (e.g. <code>"/backend-api/files"</code>)</td></tr><tr><td><code>requestHeaders</code></td><td>Yes</td><td>Stringified JSON of request headers. The <code>host</code> value sets the collection name in Akto</td></tr><tr><td><code>method</code></td><td>Yes</td><td>HTTP method of the original upload (e.g. <code>"POST"</code>)</td></tr><tr><td><code>ip</code></td><td>Yes</td><td>IP address of the caller</td></tr><tr><td><code>time</code></td><td>Yes</td><td>Unix timestamp in <strong>milliseconds</strong> of when the interaction occurred</td></tr><tr><td><code>statusCode</code></td><td>Yes</td><td>HTTP status code (e.g. <code>"200"</code>)</td></tr><tr><td><code>status</code></td><td>Yes</td><td>Same as <code>statusCode</code></td></tr><tr><td><code>tag</code></td><td>Yes</td><td>Stringified JSON of labels (e.g. <code>{"gen-ai":"Gen AI"}</code>)</td></tr><tr><td><code>metadata</code></td><td>Yes</td><td>Stringified JSON of additional metadata. Can mirror <code>tag</code></td></tr></tbody></table>

### Sample Request

```bash
curl --location 'https://<GUARDRAILS_SERVICE_URL>/api/validate/file' \
--header 'Authorization: <YOUR_AKTO_API_TOKEN>' \
--form 'file=@"/path/to/file"' \
--form 'contextSource="ENDPOINT"' \
--form 'path="/backend-api/files"' \
--form 'requestHeaders="{\"host\":\"your-agent.example.com\"}"' \
--form 'method="POST"' \
--form 'ip="<CLIENT_IP>"' \
--form 'time="1780821900129"' \
--form 'statusCode="200"' \
--form 'status="200"' \
--form 'tag="{\"gen-ai\":\"Gen AI\"}"' \
--form 'metadata="{\"gen-ai\":\"Gen AI\"}"'
```

## Steps to Test

{% stepper %}
{% step %}
**Get your Guardrails Service URL**

Contact the Akto support team to obtain your Guardrails Service URL. It will be in the format:

```
https://<account_id>-guardrails.akto.io
```

{% endstep %}

{% step %}
**Get your Akto API Token**

Follow the [Getting API Token](/akto-argus-agentic-ai-security-for-homegrown-ai/connectors/others/hybrid-saas.md#getting-api-token) steps in the Hybrid SaaS guide to get your token. Copy it, you will use it as the `Authorization` header value.
{% endstep %}

{% step %}
**Send your first request**

Use the sample `curl` below, replacing the placeholder values:

```bash
curl --location --request POST \
  'https://<GUARDRAILS_SERVICE_URL>/api/http-proxy?guardrails=true&ingest_data=true&response_guardrails=true' \
  --header 'authorization: <YOUR_AKTO_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "path": "/v1/messages",
    "requestHeaders": "{\"host\":\"my-agent.internal\"}",
    "responseHeaders": "{}",
    "method": "POST",
    "requestPayload": "{\"body\":\"What is the capital of France?\"}",
    "responsePayload": "{\"body\":\"The capital of France is Paris.\"}",
    "ip": "127.0.0.1",
    "time": "1780531200000",
    "statusCode": "200",
    "type": null,
    "status": "200",
    "akto_account_id": "1000000",
    "akto_vxlan_id": "0",
    "is_pending": "false",
    "source": "MIRRORING",
    "tag": "{\"gen-ai\":\"Gen AI\",\"source\":\"AGENTIC\"}",
    "contextSource": "AGENTIC"
  }'
```

{% endstep %}

{% step %}
**Send a file for validation (optional)**

To test file/media guardrails, use the `/api/validate/file` endpoint instead:

```bash
curl --location 'https://<GUARDRAILS_SERVICE_URL>/api/validate/file' \
--header 'Authorization: <YOUR_AKTO_API_TOKEN>' \
--form 'file=@"/path/to/file"' \
--form 'contextSource="ENDPOINT"' \
--form 'path="/backend-api/files"' \
--form 'requestHeaders="{\"host\":\"your-agent.example.com\"}"' \
--form 'method="POST"' \
--form 'ip="<CLIENT_IP>"' \
--form 'time="1780821900129"' \
--form 'statusCode="200"' \
--form 'status="200"' \
--form 'tag="{\"gen-ai\":\"Gen AI\"}"' \
--form 'metadata="{\"gen-ai\":\"Gen AI\"}"'
```

{% endstep %}

{% step %}
**Verify in the Akto dashboard**

* Log into the Akto dashboard
* Navigate to **Collections**
* Look for a collection named after the `host` value you set in `requestHeaders` (e.g. `my-agent.internal`)
* Confirm that your interaction appears with guardrail results attached
  {% endstep %}
  {% endstepper %}

## How Collections are Named

Each interaction is grouped into a **collection** in the Akto dashboard. The collection name is derived from the `host` field inside the `requestHeaders` value.

For example, if `requestHeaders` is `"{\"host\":\"cursor-agent.internal\"}"`, all interactions sent with this hostname appear in a collection named **cursor-agent.internal**.

Use a stable, descriptive hostname to keep collections organized by agent or service.

## Get Support for your Akto setup

There are multiple ways to request support from Akto. We are 24X7 available on the following:

1. In-app `intercom` support. Message us with your query on intercom in Akto dashboard and someone will reply.
2. Join our [discord channel](https://www.akto.io/community) for community support.
3. Contact <support@akto.io> for email support.
4. Contact us [here](https://www.akto.io/contact-us).