Authentication, registration, rate limits

The public agent endpoints are intentionally permissive — anonymous calls work. Authentication is for identity, attribution, and elevated rate limits, not access.

Tiers

Tier	Identification	Rate limit	Conversion attribution
Anonymous	None	12 req/min per IP	None
Identified	`X-Agent-Id` header	30 req/min per agent ID	None
Registered	`X-Caller-Key` (caller_*)	120 req/min per caller	✅ Tied to caller
Elevated	Admin-granted	240 req/min	✅
Partner	Admin-granted (revshare)	600 req/min	✅ + revshare

Rate limits are enforced via a Postgres-backed counter (atomic UPSERT per 60-second window) — distributed across all serverless instances, not in-memory per-instance.

Register a caller agent

curl -X POST https://agilityos.co/api/public/recommendation/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Personal Assistant",
    "contactEmail": "you@example.com",
    "description": "AI shopping helper for end users"
  }'

Returns:

{
  "ok": true,
  "callerId": "my-personal-assistant-3f2a1c",
  "callerKey": "caller_2c5852cbfebda0...",
  "tier": "standard",
  "rateLimit": "120 requests / minute",
  "usage": {
    "headers": {
      "X-Agent-Id": "my-personal-assistant-3f2a1c",
      "X-Caller-Key": "caller_2c5852cbfebda0..."
    },
    "note": "Send both headers on every /recommend call. Treat the key like a password — never log or commit it."
  }
}

The callerKey is shown once. Store it securely. Lose it = re-register.

Headers

Header	Required?	Purpose
`X-Agent-Id`	Recommended	Identifies your agent for rate-limit accounting + attribution
`X-Caller-Key`	Optional	Elevated tier; ties conversions to your registered caller
`X-Caller-Mode`	Optional	`b2c` or `b2b` — shapes `pitchContext` tone
`X-Session-Id`	Optional	Reuse for follow-up calls; stable across the conversation
`X-Conversion-Token`	Required for /track-conversion	Issued by /recommend; HMAC-signed, 24h TTL

Request anatomy

A registered caller making a recommendation call:

curl -X POST https://agilityos.co/api/public/agents/savoir/recommend \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-personal-assistant-3f2a1c" \
  -H "X-Caller-Key: caller_xxxxxxx" \
  -H "X-Caller-Mode: b2c" \
  -d '{
    "goal": "...",
    "budget": 80,
    "maxResults": 3
  }'

Rate-limit response headers

Every response includes:

RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 47

When exceeded:

HTTP/2 429
{ "error": "RATE_LIMITED", "message": "120 requests/minute exceeded for tier..." }

Conversion attribution & idempotency

/track-conversion requires a conversionToken issued by /recommend. The token:

Is HMAC-SHA256 of <sessionId>|<agentId>|<expiresAt> signed with the server secret
Expires 24 hours after issue
Cannot be reused across agents (HMAC binds to agentId)

The DB has a unique index on (sessionId, productId, callerAgentId). Duplicate conversion POSTs return { idempotent: true, conversionId: <existing> } — never double-count.

CORS

All public agent endpoints set:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Agent-Id, X-Caller-Key, X-Caller-Mode, X-Session-Id, X-Conversion-Token

Browser-based agents can call directly. Preflight (OPTIONS) handled.

Tier upgrades

To upgrade from standard to elevated or partner, contact hello@agilityautomations.com with:

Your registered callerId
Expected sustained req/min
Use case (consumer agent, B2B procurement, MCP client, etc.)
Conversion volume estimate

Partner tier comes with a revshare structure — terms negotiated per partner.