Agent API Overview.

The Agent API lets external systems operate your loyalty platform without a user interface. POS systems award points on purchase, AI assistants check balances and suggest rewards, and automation tools trigger loyalty actions from external events—all through a single, stateless REST API.

💡 Different from the standard API: The REST API uses session-based login tokens. The Agent API uses long-lived API keys with granular scopes—designed for machines, not humans.

What It Does

Architecture at a Glance

flowchart LR
    subgraph client ["Your System"]
        A["POS / AI / Automation"]
    end

    subgraph platform ["Reward Loyalty"]
        B["Agent API\n/api/agent/v1"]
        B --> C["Key authentication"]
        B --> D["Scope enforcement"]
        B --> E["Rate limiting"]
        B --> F["Audit logging"]
        B --> G["Business logic\n(same rules as dashboard)"]
    end

    A -- "HTTPS + JSON\nX-Agent-Key header" --> B

Key design principles:

• Stateless — No sessions, no cookies, no CSRF. Every request is self-contained.
• JSON-based — All requests and responses are JSON.
• Same business rules — The API enforces exactly the same validation, limits, and permissions as the dashboard.
• Zero-UI — No locale in the URL. Language is optional via Accept-Language header.
• Audit-logged — Every request is recorded in the Activity Logs with full traceability.

It's a Tool, Not an AI

The Agent API doesn't include an AI — it's a structured interface that AI agents (or any other system) can call as a tool. It sits alongside web search, file operations, and database queries as something an autonomous agent acts on.

graph TD
    A["Any external system\n(AI agent, POS, automation)"] --> B["Brain — LLM\n(cloud, local, or hybrid — optional)"]
    A --> C["Planning\nOrchestration layer"]
    A --> D["Tools"]
    D --> E["Browse web, read emails,\nquery databases..."]
    D --> F["Agent API\nThe loyalty platform"]

    style F fill:#f0f4ff,stroke:#a5b4fc,stroke-width:2px,color:#1e293b

Think of today's AI agents — tools like Claude (Anthropic), OpenAI's Operator, Perplexity, Google Gemini, or self-hosted models like DeepSeek and Qwen — as the "brain" side of this diagram. The Agent API is on the "tools" side. This space is evolving rapidly; by the time you read this, new players may have emerged. The API doesn't care which agent connects — it speaks plain HTTP and JSON.

Whether you're connecting an AI assistant, a POS system, or an automation pipeline, the architecture stays the same:

No LLM provider key is needed on the platform side. The Agent API only sees the X-Agent-Key header and the JSON request body. Cloud LLMs, local on-premise models (DeepSeek, Qwen, Llama), hybrid setups, and no-AI automation all work identically — a curl command is as valid an "agent" as a full autonomous AI assistant.

What's agent-ready today:

• Structured error recovery — every response includes a machine-readable retry_strategy field (no_retry, backoff, fix_request, contact_support) so agents can handle errors autonomously without human intervention.
• Self-identifying keys — the /health endpoint returns the key's role, scopes, rate limit, and owner, letting agents understand their own permissions on first contact.
• Complete endpoint reference — the Endpoint Reference documents every route, parameter, and response field. You can use this as the tool definition for your agent framework today.
• OpenAPI 3.0 spec — A dedicated Agent API specification is generated from the controllers and available at /api/agent/docs.json. Import it into Swagger UI, Postman, or any automation platform. The spec covers all 69 endpoints across partner, admin, and member roles with accurate request/response schemas. Browse the live spec →
• Tool discovery endpoint — GET /api/agent/v1/tools returns machine-readable tool definitions scoped to the authenticated key's role and permissions, in the format your agent framework expects. Your agent calls this once at startup to learn what it can do. See Tool Discovery for details.

Quick Start

1. Enable the Agent API feature

Add the following to your .env file:

FEATURE_AGENT_API=true

The Agent API is an opt-in feature. When disabled (the default), all agent routes, navigation, and key management are hidden throughout the platform.

2. Enable Agent API for a partner

As an administrator, edit the partner account and enable the Agent API permission in the Permissions tab. See Enabling & Managing Keys for details.

3. Create an Agent Key

In the partner dashboard, navigate to Integrations → Agent Keys and create a new key. Choose the appropriate permission level.

4. Copy the key (one-time display)

The full key is shown once. It looks like:

rl_agent_a8f3k2m1x9v4b7n2p5q8r1t6w3y0z4d7f0h3j6l9...

After closing the dialog, only the prefix (rl_agent_a8f3k2m1) is visible—the full key is irretrievable.

5. Make your first request

curl -X GET https://your-domain.com/api/agent/v1/health \
  -H "X-Agent-Key: rl_agent_a8f3k2m1x9v4b7n2p5q8r1t6w3y0z4d7f0h3j6l9..."

Response:

{
  "error": false,
  "data": {
    "status": "ok",
    "key": {
      "name": "POS Terminal 1",
      "prefix": "rl_agent_a8f3k2m1",
      "role": "partner",
      "scopes": ["read", "write:transactions"],
      "rate_limit": 60,
      "expires_at": null
    },
    "owner": {
      "id": "9e1a...",
      "name": "Coffee Corner",
      "type": "partner"
    }
  }
}

Base URL

All Agent API requests use:

https://your-domain.com/api/agent/v1

No locale prefix. No session token. Just the key.

Current Status & Roadmap

Shipped — Full API Coverage

All endpoints across all three roles are live and production-ready:

Shipped — Agent-Native Tooling

Next Steps

• Authentication — How keys work, security model, and error handling
• Enabling & Managing Keys — Create, revoke, and configure keys
• Scopes & Permissions — Permission levels and what each scope unlocks
• Partner Endpoints — Full endpoint reference for partner operations
• Member Endpoints — Balance, rewards, profile, and claims for members
• Admin Endpoints — Partner management, member search, and analytics
• Tool Discovery — Machine-readable tool definitions for AI agent frameworks
• Complete Endpoint Reference — Every endpoint across all roles in one page
• Error Handling — Structured error responses and retry strategies
• Audit Logging — What gets logged and how to monitor agent activity

Related Topics

• REST API Reference — The session-based API (different from Agent API)
• Partner Permissions — Enable Agent API access per partner
• Activity Logs — View agent activity audit trail
• Integrations — Other integration options (Shopify)