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, built for machines.

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, cookies, or CSRF tokens. Every request is self-contained.
• JSON-based. All requests and responses use JSON.
• Same business rules. The API enforces 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. The platform records every request in the Activity logs.

It's a tool, not an AI

The Agent API does not include an AI. It is a structured interface that AI agents (or any other system) can call as a tool. It sits alongside web search 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 (Claude, 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 evolves fast; by the time you read this, new players may have emerged. The API does not 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:

The platform side needs no LLM provider key. The Agent API sees the X-Agent-Key header and the JSON request body, nothing else. Cloud LLMs, local on-premise models (DeepSeek, Qwen, Llama), hybrid setups, and no-AI automation all work the same way. 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 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. The platform generates a dedicated Agent API specification from the controllers at /api/agent/docs.json. Import it into Swagger UI, Postman, or any automation platform. The spec covers 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

Turn on the Agent API switch under Settings → Integrations. The matching FEATURE_AGENT_API flag in .env sets the server default, the same as the store integrations.

The Agent API is an opt-in feature. While the switch is off (the default), the platform hides all agent routes, navigation, and key management. With it on, access is per plan and per partner: the partner's plan includes the Agent API, or an admin grants it on the partner's Permissions tab. A partner who already holds it keeps their keys until their plan or permission changes; once no active plan offers it and no partner holds a grant, Agent Keys stay out of every partner dashboard and off the signup plan cards and the My Plan comparison.

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, go to Integrations → Agent Keys and create a new key. Choose the permission level that fits.

4. Copy the key (one-time display)

The dashboard shows the full key once. It looks like:

rl_agent_a8f3k2m1x9v4b7n2p5q8r1t6w3y0z4d7f0h3j6l9...

After you close the dialog, only the prefix (rl_agent_a8f3k2m1) remains visible. There is no way to retrieve the full key.

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 or session token, only 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 each log entry contains 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)