API Reference

The Loopana REST API allows you to fetch messages without the SDK. Useful for server-side rendering, mobile apps, or custom integrations.

Base URL

All endpoints are served from your Convex deployment URL:

https://<your-convex-deployment>.convex.site/api/v1

Authentication

Include your API key in the X-API-Key header:

curl -H "X-API-Key: pk_live_xxx" \
  https://<deployment>.convex.site/api/v1/messages

API keys are found in Settings > API Keys in the dashboard. Live keys (pk_live_) record analytics events. Test keys (pk_test_) work identically but skip analytics tracking.

Endpoints

GET /api/v1/messages

Fetch all slots and their active messages for the project.

Query Parameters:

Parameter	Type	Required	Description
`locale`	`string`	No	Locale code for translated content (e.g., `fr`, `en-US`)
`endUserId`	`string`	No	Stable user ID for deterministic A/B test selection
`sessionId`	`string`	No	Session ID, used as fallback seed for A/B test mode

Response:

{
  "slots": [
    {
      "name": "homepage-banner",
      "mode": "stack",
      "events": [],
      "messages": [
        {
          "id": "abc123",
          "title": "Welcome!",
          "description": "Check out our new features",
          "url": "/features",
          "actionLabel": "Learn more",
          "intent": "info",
          "event": null,
          "order": 10
        }
      ]
    }
  ]
}

Message Object

Each message in the response contains:

Field	Type	Description
`id`	`string`	Unique message ID
`title`	`string`	Message title (resolved with locale if provided)
`description`	`string \| null`	Optional description
`url`	`string \| null`	Optional link URL
`actionLabel`	`string \| null`	Optional button text
`intent`	`string`	Visual style: `info`, `success`, `warning`, `destructive`, or `default`
`event`	`string \| null`	Event name, if the slot uses events
`order`	`number`	Sort order (higher = shown first)

Mode Behavior

The API applies the slot's mode before returning messages:

stack — All active messages returned, sorted by order (highest first)
ab_test — One message per slot (or per event), selected deterministically from endUserId or sessionId. The same user always sees the same message.
random — One message per slot (or per event), selected randomly on each request

Tracking Events

To record impressions, clicks, and dismissals, send events to the events endpoint:

curl -X POST \
  -H "X-API-Key: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"messageId": "abc123", "type": "impression"}' \
  https://<your-app>/api/v1/events

Event types: impression, click, dismiss

Optional fields: slotId, endUserId, sessionId