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 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:

Parameter	Value	Description
guardrails	true	Run guardrail checks on the request payload
response_guardrails	true	Run guardrail checks on the response payload
ingest_data	true	Send the interaction to the Akto dashboard for monitoring and visibility

Headers

Header	Required	Description
authorization	Yes	Your Akto API token
Content-Type	Yes	application/json

Request Body

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

{
  "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

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).

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

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.

Response and Guardrail Modes

Response Format

The guardrail verdict is returned under data.guardrailsResult:

{
  "success": true,
  "message": "Request processed successfully",
  "latencyMs": 1840,
  "data": {
    "success": true,
    "message": "Request processed successfully",
    "guardrailsResult": {
      "Allowed": false,
      "Modified": false,
      "ModifiedPayload": "",
      "Reason": "[Block] Blocked due to prompt injection",
      "behaviour": "block",
      "Metadata": {
        "policy_name": "Prompt Injection Policy",
        "rule_violated": "PromptInjection",
        "severity": "HIGH"
      }
    }
  }
}

Field	Type	Description
Allowed	boolean	true when no guardrail was violated. false when a policy was violated, regardless of its mode. Always read it together with behaviour
behaviour	string	The Rule Behaviour of the violated policy: block, alert, human_approval, or warn (legacy). Omitted when nothing was violated
Modified	boolean	true when a policy masked or redacted part of the payload
ModifiedPayload	string	The masked payload. Forward this instead of the original when Modified is true
Reason	string	Explanation of the verdict, prefixed with the mode, e.g. [Block], [Alert only], [Approval required]
Metadata	object	The violated policy (policy_name), rule (rule_violated), severity, and violation details

Field casing

Allowed, Modified, ModifiedPayload, Reason, and Metadata are PascalCase, while behaviour is lowercase. Human Approval responses (below) use lowercase allowed. Read both casings to be safe.

When both guardrails=true and response_guardrails=true are set, guardrailsResult also carries requestResult and responseResult with the verdict for each side. The top-level Allowed is false if either side was violated, so read behaviour from the side that was violated.

Guardrail Modes

Each guardrail policy has a Rule Behaviour that decides what happens when it is violated. Set it in the policy's Scope section. See Create Guardrail Policies.

Akto does not sit inline in your traffic when you use this API. It returns the verdict, and your application enforces it. Use behaviour to decide what to do:

Mode	behaviour	Allowed	What your application should do
Block	block	false	Stop the request or response. Return an error or a safe message to the user
Alert	alert	false	Let it through. Akto records the violation in Guardrail Activity for review
Human Approval	human_approval	false	Hold the request and poll for the approver's decision (see below)
Mask / Redact	alert (with Modified: true)	true	Forward ModifiedPayload instead of the original payload
No violation	omitted	true	Let it through

Do not rely on Allowed alone.

In Alert mode Allowed is still false, because a policy was violated. If you block on Allowed == false, alert-mode policies will block traffic. Block only when behaviour is block (or any value other than alert).

If several policies are violated, the strictest mode is returned: Block > Human Approval > Alert. A missing or unknown behaviour on a violation should be treated as Block.

Sample enforcement logic

result = resp.json()["data"]["guardrailsResult"]
allowed = result.get("Allowed", result.get("allowed", True))
behaviour = (result.get("behaviour") or "").lower()
payload = original_payload

if result.get("Modified"):
    payload = result["ModifiedPayload"]        # Mask / Redact: forward masked payload
if allowed or behaviour == "alert":
    forward(payload)                           # No violation, or Alert mode
elif behaviour == "human_approval":
    wait_for_approval(result["activityId"])    # Human Approval: poll (see below)
else:
    reject(result.get("Reason"))               # Block (default)

Human Approval Mode

When a policy set to Human Approval is violated, the attempt is sent to your approvers in the Needs Approval tab of Guardrail Activity. The response carries an activityId and a status:

{
  "success": true,
  "message": "Request processed successfully",
  "data": {
    "guardrailsResult": {
      "allowed": false,
      "behaviour": "human_approval",
      "status": "pending",
      "activityId": "<ACTIVITY_ID>",
      "reason": "[Approval required] Held for approval due to ...",
      "modified": false
    }
  }
}

Poll for the decision by calling the same endpoint with only the activityId. Akto looks up the decision and does not re-run the guardrails:

curl --location --request POST 'https://<GUARDRAILS_SERVICE_URL>/api/http-proxy' \
  --header 'authorization: <YOUR_AKTO_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"activityId": "<ACTIVITY_ID>"}'

status	allowed	Meaning
pending	false	No decision yet. Keep holding the request and poll again
approved	true	An approver allowed it. Forward the request
blocked	false	An approver denied it. Reject the request

Poll every few seconds, and set a timeout after which your application treats the request as blocked. See Manage Human Approval Requests for the approver workflow.

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

Header	Required	Description
Authorization	Yes	Your Akto API token

Form Fields

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

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

Sample Request

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

1

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

2

Get your Akto API Token

Follow the Getting API Token steps in the Hybrid SaaS guide to get your token. Copy it, you will use it as the Authorization header value.

3

Send your first request

Use the sample curl below, replacing the placeholder values:

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"
  }'

4

Send a file for validation (optional)

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

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\"}"'

5

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

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 for community support.

3. Contact [e-mail] for email support.

4. Contact us here.