Complete Endpoint Reference

Every agent API endpoint, read from source. Base URL: /api/agent/v1 (69 endpoints total).

All endpoints require a valid agent key via the X-Agent-Key header. See Authentication for details.

💡 Interactive version available: Browse the full OpenAPI spec in Swagger UI → or download the raw JSON spec for import into Postman or code generators. For machine-readable tool definitions, see Tool Discovery.

Global

Health Check

GET /health

Scope: Any valid key (no specific scope required) Role: All (partner, member, admin)

Returns key identity, scopes, rate limit, and connectivity status.

Response fields: status, key.name, key.prefix, key.role, key.scopes[], key.rate_limit, key.expires_at, key.created_at, key.last_used_at, owner.id, owner.name, owner.type

Tool Discovery

GET /tools

Scope: Any valid key (no specific scope required) Role: All (partner, member, admin)

Returns machine-readable tool definitions scoped to the authenticated key's role and permissions. Pass ?format=openai, ?format=anthropic, ?format=mcp, or ?format=generic (default) to get definitions in your agent framework's format.

This endpoint is excluded from its own tool list — a tool that lists tools is meta-noise for agents.

Query parameters: format (string, default: generic)

Response fields: tools[], meta.role, meta.format, meta.tool_count, meta.cached

See Tool Discovery for full format examples and integration guides.

Partner Endpoints

All partner endpoints are prefixed with /partner and require a partner agent key.

Clubs

Clubs are organizational units that group cards, staff, and tiers.

Create/Update body:

Guards: Protected clubs (is_undeletable) cannot be deleted.

Loyalty Cards

Cards define the points economy: currency, earning rate, limits, expiry.

Create body:

Update: All fields optional. club_id can be changed (ownership verified).

Permission gate: loyalty_cards_permission Limit gate: loyalty_cards_limit

Rewards

Redeemable items that members exchange points for.

Create body:

Permission gate: loyalty_cards_permission Limit gate: rewards_limit

Transactions

The core earn-and-burn flow for POS/CRM integrations.

List Transactions

GET /partner/transactions

Query parameters:

Response per item: id, event, points, purchase_amount, currency, member_id, card_id, reward_id, staff_id, staff_name, note, expires_at, created_at

Record a Purchase

POST /partner/transactions/purchase

† Either purchase_amount or points must be provided.

Response: transaction_id, points_awarded, member_balance, purchase_amount, card_id, member_id

Redeem a Reward

POST /partner/transactions/redeem

Response: transaction_id, points_deducted, member_balance, new_balance, reward_id, reward.id, reward.title, card_id, member_id

Members

Read-only member access for partners. Members self-register or are auto-enrolled via transactions.

List query parameters:

Show: The {id} parameter accepts UUID, email, member_number, or unique_identifier.

Member response: id, unique_identifier, name, email, locale, currency, time_zone, last_login_at, created_at, updated_at, avatar, is_anonymous

Balance response: member_id, card_id, balance, currency

Stamp Cards

Digital punch cards. Members collect stamps and earn a reward when complete.

Create body:

Use canonical field names only: stamps_expire_days and requires_physical_claim.

Permission gate: stamp_cards_permission Limit gate: stamp_cards_limit

Add Stamps

POST /partner/stamp-cards/{id}/stamps

Response: stamps_added, current_stamps, stamps_required, completed, pending_rewards

Redeem Stamp Reward

POST /partner/stamp-cards/{id}/redeem

Response: reward_title, reward_value, remaining_rewards

Vouchers

Digital discount vouchers with usage tracking.

Create body:

Use canonical field names only: type, value, max_uses_total, valid_from, and valid_until.

Permission gate: vouchers_permission Limit gate: vouchers_limit

Validate Voucher

POST /partner/vouchers/validate

Response: valid, voucher_id, code, name, type, value, currency, discount_amount, capped, original_amount, final_amount, times_used, remaining_uses, valid_until

Redeem Voucher

POST /partner/vouchers/{id}/redeem

Response: voucher_id, code, type, member_id, discount_amount, points_awarded, remaining_uses, redemption_id

Validation checks: Active, within the validity window, and not exhausted (times_used < max_uses_total when a total cap exists).

Tiers

Loyalty levels within a club (e.g., Bronze, Silver, Gold).

Create body:

Staff

Staff members who operate loyalty cards (scan, award, redeem).

Create body:

Use the canonical field club_id.

Update: All fields optional. email uniqueness enforced excluding current record.

Limit gate: staff_members_limit

Member Endpoints

All member endpoints are prefixed with /member and require a member agent key.

Profile

Show response: id, name, email, locale, unique_identifier, avatar, is_anonymous, has_interacted, first_interaction_at, created_at

Update body:

Email cannot be changed via API — requires the full auth flow.

Balance & Cards

Balance response per card: card_id, card_title, balance, currency

Card detail response: id, name, title, description, currency, balance, bg_color, text_color, is_active

Transaction History

Response per transaction: id, card_id, card_title, event, points, points_used, purchase_amount, currency, reward_title, reward_points, note, expires_at, created_at

Member transaction responses are filtered to member-relevant fields only — no partner emails, internal config, or admin metadata.

Rewards

Rewards list response per item: id, title, description, points, image, active_from, expiration_date, can_afford, best_balance, deficit

The can_afford and deficit fields enable "You need X more points" messaging.

Claim: Submits a claim intent — NOT a direct redemption. Staff must confirm via their dashboard or the partner agent API. This prevents fraud in physical locations.

Claim response: status (claim_submitted), reward_id, reward_title, points_required, card_id, card_title, current_balance, message

Discover

Members discover cards via homepage browsing or QR code/shared link scanning.

Browse

Returns all active, visible cards across all partners grouped by type:

Response: data.cards[], data.stamp_cards[], data.vouchers[]

Each item includes type-specific display fields and the member's enrollment/follow status.

Resolve

POST /member/discover/resolve

One of url or identifier is required.

Supported URL patterns:

• https://example.com/{locale}/card/{uuid}
• https://example.com/{locale}/stamp-card/{uuid}
• https://example.com/{locale}/voucher/{uuid}
• https://example.com/{locale}/follow/{uuid}

Follow / Unfollow

POST /member/discover/follow
POST /member/discover/unfollow

Follow is idempotent — calling it twice is safe.

Admin Endpoints

All admin endpoints are prefixed with /admin and require an admin agent key.

Partners

List query parameters:

Partner detail response: id, name, email, locale, currency, time_zone, is_active, avatar, created_at, permissions{}, usage{}

Permissions body (all optional):

Deactivate invalidates all associated agent keys immediately.

Partners are NOT created/deleted via agent API — they self-register or are managed through the admin dashboard.

Members (Platform-wide)

List query parameters:

Member detail response: id, name, email, unique_identifier, locale, is_active, is_anonymous, created_at, card_balances[]

Each card_balance includes: card_id, card_title, club_name, balance, currency

Read-only. Member lifecycle is managed through transactions (auto-enrollment) or member self-service.

Analytics

Overview response: total_partners, active_partners, total_members, total_cards, total_stamp_cards, total_vouchers, transactions_today, transactions_this_week, transactions_this_month

Per-partner response: partner_id, partner_name, is_active, loyalty_cards, stamp_cards, vouchers, rewards, staff_members, total_transactions, transactions_today, total_members_enrolled

Endpoint Count Summary