Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Shashank-H/gaiter-gaurd/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

POST /proxy
Main proxy endpoint for agents to forward requests through the gateway. Handles authentication, validation, credential injection, risk assessment, and idempotency.

​
Authentication

Requires Agent-Key header with valid agent API key. 
Agent-Key: your-agent-key-here

​
Request Headers

​
Agent-Key
string
required
Agent API key for authentication
​
Idempotency-Key
string
Idempotency key for request deduplication. Required for POST and PATCH requests. Header takes precedence over body field if both are provided.

​
Request Body

​
targetUrl
string
required
Target URL to forward the request to. Must match a registered service’s baseUrl and pass SSRF validation.Example: https://api.github.com/repos/owner/repo/issues
​
method
string
required
HTTP method for the request.Allowed values: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
​
headers
object
default:"{}"
Request headers to forward to the target service. Do not include Authorization or credential headers - these are injected automatically.Example: {"Content-Type": "application/json", "Accept": "application/json"}
​
body
string
Request body as a JSON string. Nullable for methods that don’t require a body.Example: "{\"title\": \"Bug report\", \"body\": \"Description\"}"
​
intent
string
required
Human-readable description of what this request is attempting to do. Used for risk assessment and audit logging.Constraints: 1-500 charactersExample: "Create a new GitHub issue for bug report"
​
idempotencyKey
string
Idempotency key for request deduplication. Required for POST and PATCH requests. Can be provided via header instead.Constraints: 1-255 charactersExample: "issue-creation-20260303-001"

​
Response

​
Success Response (200 OK)

Request was successfully forwarded and completed.
​
status
number
HTTP status code from the target service
​
headers
object
Response headers from the target service, including:
  • Content-Type: Preserved from target response
  • X-Proxy-Status: Always "forwarded" for successful requests
  • X-Idempotency-Status: "processed" if idempotency key was used
​
body
string
Response body from the target service (as received)

​
Risk-Blocked Response (428 Precondition Required)

Request was blocked due to high risk score and requires human approval.
​
error
string
Error message: "Request requires human approval"
​
action_id
string
Unique identifier for the approval queue entry. Use this to poll status via GET /status/:actionId.
​
risk_score
number
Risk assessment score (0-100) that triggered the block.
​
risk_explanation
string
Human-readable explanation of why the request was flagged as risky.
​
status_url
string
URL to poll for approval status: /status/:actionId

​
Error Responses

​
401 Unauthorized
Invalid or missing Agent-Key header
​
400 Bad Request
  • Invalid request body schema
  • Invalid URL format
  • Missing required idempotencyKey for POST/PATCH
  • Invalid HTTP method
​
403 Forbidden
  • Target URL hostname doesn’t match service baseUrl (SSRF prevention)
  • Target URL path doesn’t start with service baseUrl path
  • Access to private IP ranges blocked
  • Access to localhost blocked
​
404 Not Found
No service found matching target URL, or agent doesn’t have access to the service
​
409 Conflict
Request with this idempotency key is already being processed
​
413 Payload Too Large
Response size exceeds 10MB limit
​
428 Precondition Required
Request blocked by risk assessment - see response body for action_id to track approval
​
500 Internal Server Error
  • No credentials found for service
  • Failed to decrypt credentials
  • Unsupported authentication type
​
502 Bad Gateway
Failed to forward request to target service
​
504 Gateway Timeout
Request timeout (30 second limit exceeded)

​
Examples

curl -X POST https://api.gaiterguard.com/proxy \
  -H "Agent-Key: your-agent-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://api.github.com/repos/owner/repo/issues",
    "method": "GET",
    "headers": {
      "Accept": "application/json"
    },
    "intent": "List all issues in the repository"
  }'

​
Request Flow

  1. Authentication - Validate Agent-Key header
  2. Schema Validation - Validate request body against schema
  3. Idempotency Check - Check for cached response (if key provided)
  4. Service Resolution - Find matching service and verify agent access
  5. SSRF Validation - Validate target URL against service baseUrl
  6. Risk Assessment - Evaluate request risk score
  7. Credential Injection - Inject service credentials based on auth type
  8. Forward Request - Send request to target service (30s timeout, 10MB limit)
  9. Cache Response - Store response for idempotency (if key provided)
  10. Return Response - Return target service response with proxy metadata

​
SSRF Protection

The gateway implements multiple layers of SSRF protection:
  • Hostname matching: Target hostname must match service baseUrl hostname
  • Path prefix validation: Target path must start with service baseUrl path
  • Private IP blocking: Blocks 127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x, ::1, fc00:, fe80:
  • Localhost blocking: Blocks localhost hostname
  • Protocol restriction: Only http:// and https:// allowed

​
Idempotency Behavior

  • Required for POST and PATCH methods
  • Can be provided via Idempotency-Key header or idempotencyKey body field
  • Header takes precedence if both are provided
  • Cached responses are returned immediately (status 200)
  • Requests in-flight return 409 Conflict
  • Cache is scoped to agent + key + request hash (method:url:body)

Build docs developers (and LLMs) love

Get started for freeTalk to us