API Reference

The Korrero REST API allows you to fetch notifications and track user interactions programmatically. All endpoints are publicly accessible and designed for easy integration with web applications.

Base URL

All API requests should be made to: https://api.korrero.com/api/v1/public

Authentication

Authentication Requirements

Get Notifications requires your project API key in the URL path:

GET /api/v1/public/{your-api-key}/notifications

Tracking endpoints (both simple and enhanced) do not require authentication and are publicly accessible.

Rate Limiting

Rate limits prevent API abuse and ensure fair usage across all users. Current limits:

• All endpoints: 1000 requests per minute per IP (60 seconds window)

Exceeding limits

If you exceed rate limits, you'll receive a 429 Too Many Requests response with the message "Too many requests from this IP, please try again later." Implement exponential backoff in your retry logic.

Endpoints

Get Notifications

Fetches notifications for your project based on API key settings.

Endpoint

GET /api/v1/public/{apiKey}/notifications

Parameters

Parameter	Location	Type	Required	Description
apiKey	Path	String	✅	Your project API key (32-64 characters)

Response

Success (200)

[
  {
    "id": "notif_abc123",
    "message": "\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Welcome to our platform!\"}]}]}",
    "image": "https://api.korrero.com/uploads/banner.jpg",
    "action": {
      "type": "LINK",
      "data": {
        "url": "https://example.com/welcome",
        "target": "_blank"
      }
    },
    "preset": "default",
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-12-31T23:59:59.000Z"
  }
]

Rich Content Format

The message field uses a structured JSON format for rich text content. This structure is based on the ProseMirror content model, commonly implemented by the Tiptap editor framework.

This Abstract Syntax Tree (AST) representation is used to ensure a consistent and strictly defined document structure.

Element	Description
Structure	{"type":"doc", "content":[...]}
Reference	Tiptap StarterKit Documentation

Note: For all available node types (e.g., headings, lists, bold) and their JSON schemas, please check the Tiptap documentation linked above or use functions from KorrreroJS Rich Text Rendering.

Error Responses

• 401 Unauthorized - Missing API key in path
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Filtering Behavior

Time Filtering (based on API key settings):

• Current notifications: Always included (active now)
• Past notifications: Only if showPast is enabled
• Future notifications: Only if showFuture is enabled

Limits & Ordering:

• Ordered by API key orderBy setting (default: createdAt_desc)

Track Interaction (Simple)

Track basic user interactions with notifications.

Endpoint

POST /api/v1/public/track/{notificationId}

Parameters

Parameter	Location	Type	Required	Description
notificationId	Path	String	✅	Notification ID to track

Request Body

{
  "type": "impression" | "click"
}

Response

Success (204) - No content (interaction tracked)

Error Responses

• 400 Bad Request - Invalid interaction type
• 404 Not Found - Notification not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Example Request

curl -X POST \
  https://api.korrero.com/api/v1/public/track/notif_abc123 \
  -H 'Content-Type: application/json' \
  -d '{"type": "click"}'

Track Interaction (Enhanced)

Track detailed user interactions with custom metadata and enhanced analytics.

Endpoint

POST /api/v1/public/track/{notificationId}/enhanced

Authentication

No authentication required. Bearer tokens are accepted but not mandatory.

Parameters

Parameter	Location	Type	Required	Description
notificationId	Path	String	✅	Notification ID to track

Request Body

{
  "type": "impression" | "click" | "conversion",
  "timestamp": "2024-01-15T14:30:00Z", // Optional, server uses current time if not provided
  "metadata": { // Optional custom data
    "source": "homepage_banner",
    "campaign": "spring_sale_2024",
    "customField": "value123"
  }
}

Response

Success (204) - No content (interaction tracked)

Error Responses

• 400 Bad Request - Invalid interaction type
• 404 Not Found - Notification not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Example Request

curl -X POST \
  https://api.korrero.com/api/v1/public/track/notif_abc123/enhanced \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "conversion",
    "metadata": {
      "conversionValue": 99.99,
      "conversionType": "purchase"
    }
  }'

Response Schemas

PublicNotification Object

interface PublicNotification {
  id: string;           // Unique notification identifier
  message: string;      // Message content (may contain HTML/rich text)
  image: string | null; // URL to notification image
  action: {
    type: "NO_ACTION" | "LINK" | "CLOSE";
    data: {
      url: string;
      target: "_blank" | "_self";
    } | null;
  };
  preset: string;       // Display preset name
  startDate: string;    // ISO 8601 datetime when notification becomes active
  endDate: string | null; // ISO 8601 datetime when notification expires
}

Error Response

interface ErrorResponse {
  error: string;        // Human-readable error message
  code?: string;        // Error code for programmatic handling
  details?: object;     // Additional error details
}

Best Practices

Error Handling

try {
  const response = await fetch('/api/v1/public/notifications');
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.error);
  }
} catch (error) {
  console.error('Network error:', error);
}

Rate Limit Handling

async function makeRequest(url: string, options: RequestInit) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    // Implement exponential backoff
    await new Promise(resolve => setTimeout(resolve, 1000));
    return makeRequest(url, options);
  }

  return response;
}

Authentication

// Include your public API key in requests
const API_KEY = 'your_project_api_key_here'; // Safe to include in client code

const headers = {
  'Content-Type': 'application/json'
};

KorreroJS Integration

For easier integration, consider using the KorreroJS SDK which handles:

• Automatic authentication
• Error handling and retries
• Response parsing
• TypeScript support

Support

For API-related questions or issues:

• Email: [email protected]
• Documentation: See the KorreroJS Reference for client-side integration
• OpenAPI Spec: Available at docs/openapi.yaml endpoint for detailed schema information