Guard API Documentation

Rate limiting and cost control API for workflow safety.

Quick Reference

Base URL:

https://api.ainoflow.io

Authentication:

Authorization: Bearer your_api_key_here

Core Concepts

Guard Key

• Unique identifier for each rate limit (up to 512 characters)
• Represents what you're rate-limiting (e.g., send-emails, openai-calls)
• Combined scope/project/key must be unique per policy type

Policy Engine

• Policies auto-created on first check with rateMax/rateWindow
• Subsequent checks use stored policy (no need to repeat params)
• If params differ from stored policy → 409 Conflict (or pass allowPolicyOverwrite=true to update inline)
• Manage policies via CRUD endpoints

Fixed Window Algorithm

• Time divided into fixed windows of window seconds
• Counter resets when a new window starts
• Denied requests are NOT counted
• Atomic operations for thread safety

Fail-Safe Behavior

• Default: Fail-closed - if the service is unavailable, executions are blocked
• Option: Fail-open - pass ?failOpen=true to allow when the service is temporarily unavailable
• returnSuccess - pass ?returnSuccess=true to get 200 OK for denied requests

Counter Endpoints

POST

Increment Counter (Check Rate Limit)

/api/v1/guard/{key}/counter

Increment counter and check if execution is allowed. On first call with rateMax/rateWindow, a policy is auto-created.

Path Parameters:

key

required

- Guard identifier (e.g., "send-emails"). Max 512 characters.

Query Parameters:

rateMax

optional

- Max executions per window (1–1,000,000). Required on first call.

rateWindow

optional

- Window size in seconds (1–86,400). Required on first call.

returnSuccess

optional

- If true, return 200 OK for denied instead of 429 (default: false)

failOpen

optional

- If true, allow execution when the service is temporarily unavailable (default: false)

allowPolicyOverwrite

optional

- If true, update the stored policy when rateMax/rateWindow differ from existing values instead of returning 409 (default: false)

Response (200 OK - Allowed):

{
  "key": "send-emails",
  "allowed": true,
  "remaining": 58,
  "resetsIn": 2145,
  "rateLimit": {
    "current": 42,
    "max": 100,
    "window": 3600
  }
}

Response (429 Too Many Requests - Denied):

{
  "key": "send-emails",
  "allowed": false,
  "remaining": 0,
  "resetsIn": 855,
  "rateLimit": {
    "current": 100,
    "max": 100,
    "window": 3600
  }
}

Includes Retry-After header with seconds until window resets.

GET

Read Counter

/api/v1/guard/{key}/counter

Read current counter status without incrementing. For occasional checks and debugging.

Response (200 OK):

{
  "key": "send-emails",
  "exists": true,
  "rateLimit": {
    "current": 42,
    "max": 100,
    "window": 3600,
    "resetsIn": 2145
  }
}

DELETE

Delete Counter (Reset)

/api/v1/guard/{key}/counter

Clear (reset) rate limit counters. Policies remain intact. For debugging only.

Response (200 OK):

{
  "key": "send-emails",
  "success": true
}

Policy Management Endpoints

GET

List All Policies

/api/v1/guard/policies

List all Guard policies for the current scope and project.

GET

List Policies for Key

/api/v1/guard/{key}/policies

List all policies attached to a specific key.

GET

Get Policy by ID

/api/v1/guard/policies/{id}

Get a specific policy by its ID.

POST

Create Policy

/api/v1/guard/policies

Create a new policy for a key. Each key can have at most one policy per type.

Request Body:

{
  "key": "send-emails",
  "type": "RateLimit",
  "configuration": { "max": 100, "window": 3600 },
  "enabled": true,
  "failOpen": false
}

PUT

Update Policy

/api/v1/guard/policies/{id}

Update an existing policy's configuration. Type cannot be changed.

DELETE

Delete Policy

/api/v1/guard/policies/{id}

Delete a single policy by ID.

DELETE

Delete All Policies for Key

/api/v1/guard/{key}/policies

Delete all policies attached to a specific key.

Example Usage

cURL Examples

Check rate limit (first call - auto-creates policy)

curl -X POST "https://api.ainoflow.io/api/v1/guard/send-emails/counter?rateMax=100&rateWindow=3600" \
  -H "Authorization: Bearer YOUR_API_KEY"

Check rate limit (subsequent - uses stored policy)

curl -X POST "https://api.ainoflow.io/api/v1/guard/send-emails/counter" \
  -H "Authorization: Bearer YOUR_API_KEY"

Read counter status

curl "https://api.ainoflow.io/api/v1/guard/send-emails/counter" \
  -H "Authorization: Bearer YOUR_API_KEY"

Reset counter

curl -X DELETE "https://api.ainoflow.io/api/v1/guard/send-emails/counter" \
  -H "Authorization: Bearer YOUR_API_KEY"

n8n / Make.com Integration

Simple Rate Limit Check Pattern

Add Guard rate limiting to any workflow in minutes

1. HTTP Request Node (Guard Check - first time, set limits):
   POST /api/v1/guard/{{$json.workflow_name}}/counter?rateMax=100&rateWindow=3600

2. IF Node:
   Check: $.allowed == true

3. True Branch:
   → Execute workflow (your business logic)

4. False Branch:
   → Skip (rate limited, wait for resetsIn seconds)

After the first run, subsequent calls can omit rateMax/rateWindow - the stored policy is used automatically.

HTTP Status Codes

200

OK - Allowed (or denied when returnSuccess=true), counter read, counter reset, policy operations

400

Bad Request - Invalid parameters or no policy found and rateMax/rateWindow not provided

401

Unauthorized - Missing or invalid API key

404

Not Found - No policies found for this key (GET/DELETE counter, policy endpoints)

409

Conflict - rateMax/rateWindow differ from existing policy (pass allowPolicyOverwrite=true to update inline), or policy type already exists for key

429

Too Many Requests - Rate limit exceeded. Includes Retry-After header.

500

Internal Server Error - Server error

Best Practices

Key Naming

• Use meaningful names: send-emails, openai-calls
• Name keys after the action being protected
• URL-encode special characters in the path

Window Strategy

• 60s for burst protection
• 3600s for hourly limits
• 86400s for daily limits

Set Limits on First Call

• Pass rateMax/rateWindow on first check
• Subsequent calls use stored policy
• Don't change limits mid-key

Handle Denials

• Check allowed flag
• Use resetsIn for retry timing
• Use returnSuccess=true for n8n

Ready to Get Started?

Create your free account and start protecting your workflows from overruns in minutes.

Get API Key Learn More