REST API Reference

Complete reference for all Retenshun API endpoints. All requests use JSON and return JSON.

Base URL

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

Authentication

All API requests require authentication via the x-api-key header or Authorization: Bearer header.

# Option 1: x-api-key header
curl -X GET https://your-domain.com/api/v1/users \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

# Option 2: Authorization Bearer header
curl -X GET https://your-domain.com/api/v1/users \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

Public key (pk_live_...) — Use in browser/client-side code. Can track events, identify users, and manage push tokens.

Secret key (sk_live_...) — Server-side only. Full access to all endpoints. Never expose in client code.

Rate Limiting

API requests are rate-limited per project. If you exceed the limit, you'll receive a 429 Too Many Requests response. Use exponential backoff to retry.

Error Responses

Errors return a consistent JSON format:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "status": 401
}

Endpoints

Events5Users5Segments5Automations4Campaigns4Templates4Messages2News Feed4AI Content1Channels2Push Tokens3Webhooks1API Keys3Team2Reports1

Events

Track and query user events.

POST/api/v1/events

Track a single event

Auth: API Key (public or secret)

Request Body

{
  "event": "purchase",
  "user_id": "user_123",
  "anonymous_id": "anon_abc123",
  "properties": {
    "amount": 49.99,
    "product_id": "prod_1"
  }
}

Response

{ "event": { "id": "evt_abc123", "eventName": "purchase", "userId": "...", ... } }

Accepts both SDK format (event, user_id) and legacy format (eventName, userId). Users are auto-created if not found.

POST/api/v1/events/batch

Batch ingest events (SDK)

Auth: API Key (public or secret)

Request Body

{
  "batch": [
    {
      "type": "identify",
      "user_id": "user_123",
      "anonymous_id": "anon_abc",
      "properties": { "email": "john@example.com", "name": "John" }
    },
    {
      "type": "track",
      "event": "button_clicked",
      "user_id": "user_123",
      "properties": { "button": "signup_cta" },
      "timestamp": "2026-03-09T12:00:00Z"
    }
  ]
}

Response

{ "success": true, "processed": 2, "errors": 0 }

Accepts up to 100 items per batch. Supports both "identify" and "track" types. Users are auto-created if not found.

GET/api/v1/events

List events

Auth: API Key (secret)

Query Parameters

event, user, search, page, limit

Response

{ "events": [...], "pagination": { "page": 1, "limit": 50, "total": 142, "totalPages": 3 } }
GET/api/v1/events/:id

Get a single event

Auth: API Key (secret)

Response

{ "id": "evt_abc", "eventName": "purchase", "userId": "...", "properties": {...}, ... }
DELETE/api/v1/events/:id

Delete an event

Auth: API Key (secret)

Response

{ "deleted": true }

Users

Manage end-user profiles and properties.

POST/api/v1/users/identify

Identify / upsert a user (SDK)

Auth: API Key (public or secret)

Request Body

{
  "user_id": "user_123",
  "anonymous_id": "anon_abc123",
  "properties": {
    "email": "john@example.com",
    "name": "John Doe",
    "plan": "pro"
  }
}

Response

{ "success": true, "user": { "id": "...", "externalId": "user_123" } }

Creates the user if not found, or updates properties if they already exist. The "email" and "name" fields are extracted to top-level columns.

GET/api/v1/users

List users

Auth: API Key (secret)

Query Parameters

search, page, limit, filter (active|inactive)

Response

{ "users": [...], "total": 1024, "page": 1 }
GET/api/v1/users/:id

Get a user

Auth: API Key (secret)

Response

{ "id": "user_123", "email": "john@example.com", "properties": {...}, ... }
PUT/api/v1/users/:id

Update a user

Auth: API Key (secret)

Request Body

{
  "email": "new@example.com",
  "properties": {
    "plan": "enterprise",
    "timezone": "America/New_York"
  }
}

Response

{ "id": "user_123", "email": "new@example.com", ... }
DELETE/api/v1/users/:id

Delete a user

Auth: API Key (secret)

Response

{ "deleted": true }

Segments

Create and manage user segments for targeting.

GET/api/v1/segments

List segments

Auth: API Key (secret)

Response

{ "segments": [{ "id": "seg_1", "name": "Power Users", "userCount": 342, ... }] }
POST/api/v1/segments

Create a segment

Auth: API Key (secret)

Request Body

{
  "name": "Power Users",
  "description": "Users with 10+ sessions",
  "rules": [
    { "field": "sessionCount", "operator": "gte", "value": 10 }
  ]
}

Response

{ "id": "seg_1", "name": "Power Users", ... }
PUT/api/v1/segments/:id

Update a segment

Auth: API Key (secret)

Request Body

{ "name": "Super Users", "rules": [...] }

Response

{ "id": "seg_1", "name": "Super Users", ... }
DELETE/api/v1/segments/:id

Delete a segment

Auth: API Key (secret)

Response

{ "deleted": true }
POST/api/v1/segments/estimate

Estimate segment size

Auth: API Key (secret)

Request Body

{ "rules": [{ "field": "plan", "operator": "eq", "value": "pro" }] }

Response

{ "estimatedCount": 287 }

Automations

Build event-driven automation workflows.

GET/api/v1/automations

List automations

Auth: API Key (secret)

Response

{ "automations": [...] }
POST/api/v1/automations

Create an automation

Auth: API Key (secret)

Request Body

{
  "name": "Welcome Sequence",
  "triggerType": "EVENT",
  "triggerEvent": "signed_up",
  "active": true,
  "steps": [
    { "type": "SEND_EMAIL", "templateId": "tpl_1", "delay": 0 },
    { "type": "WAIT", "delay": 259200 },
    { "type": "SEND_EMAIL", "templateId": "tpl_2" }
  ]
}

Response

{ "id": "auto_1", "name": "Welcome Sequence", ... }
PUT/api/v1/automations/:id

Update an automation

Auth: API Key (secret)

Request Body

{ "name": "Updated Welcome", "active": false }

Response

{ "id": "auto_1", "name": "Updated Welcome", ... }
DELETE/api/v1/automations/:id

Delete an automation

Auth: API Key (secret)

Response

{ "deleted": true }

Campaigns

Send one-time or scheduled messages to segments.

GET/api/v1/campaigns

List campaigns

Auth: API Key (secret)

Response

{ "campaigns": [...] }
POST/api/v1/campaigns

Create a campaign

Auth: API Key (secret)

Request Body

{
  "name": "Spring Sale",
  "channel": "EMAIL",
  "segmentId": "seg_1",
  "templateId": "tpl_3",
  "scheduledAt": "2026-04-01T10:00:00Z"
}

Response

{ "id": "camp_1", "name": "Spring Sale", "status": "SCHEDULED", ... }
PUT/api/v1/campaigns/:id

Update a campaign

Auth: API Key (secret)

Request Body

{ "name": "Spring Mega Sale" }

Response

{ "id": "camp_1", ... }
DELETE/api/v1/campaigns/:id

Delete a campaign

Auth: API Key (secret)

Response

{ "deleted": true }

Templates

Manage reusable message templates for email, push, and in-app.

GET/api/v1/templates

List templates

Auth: API Key (secret)

Query Parameters

channel (EMAIL|PUSH|IN_APP), ai (true|false)

Response

{ "templates": [...] }
POST/api/v1/templates

Create a template

Auth: API Key (secret)

Request Body

{
  "name": "Welcome Email",
  "channel": "EMAIL",
  "subject": "Welcome to {{company}}!",
  "body": "<h1>Hi {{name}}</h1><p>Thanks for joining.</p>",
  "tags": ["onboarding"]
}

Response

{ "id": "tpl_1", "name": "Welcome Email", ... }
PUT/api/v1/templates/:id

Update a template

Auth: API Key (secret)

Request Body

{ "subject": "Welcome aboard, {{name}}!" }

Response

{ "id": "tpl_1", ... }
DELETE/api/v1/templates/:id

Delete a template

Auth: API Key (secret)

Response

{ "deleted": true }

Messages

Send messages directly via API.

POST/api/v1/messages

Send a message

Auth: API Key (secret)

Request Body

{
  "userId": "user_123",
  "channel": "EMAIL",
  "subject": "Your order shipped!",
  "body": "<p>Your order #1234 is on its way.</p>"
}

Response

{ "id": "msg_1", "status": "sent" }
GET/api/v1/messages

List sent messages

Auth: API Key (secret)

Query Parameters

userId, channel, page, limit

Response

{ "messages": [...], "total": 50 }

News Feed

Manage in-app news feed items.

GET/api/v1/news

List news items

Auth: API Key (secret)

Response

{ "items": [...] }
POST/api/v1/news

Create a news item

Auth: API Key (secret)

Request Body

{
  "title": "New Feature: Dark Mode",
  "body": "We just launched dark mode!",
  "published": true
}

Response

{ "id": "news_1", ... }
PUT/api/v1/news/:id

Update a news item

Auth: API Key (secret)

Request Body

{ "title": "Updated title" }

Response

{ "id": "news_1", ... }
DELETE/api/v1/news/:id

Delete a news item

Auth: API Key (secret)

Response

{ "deleted": true }

AI Content

Generate AI-powered message content.

POST/api/v1/ai/generate

Generate content with AI

Auth: API Key (secret)

Request Body

{
  "channel": "PUSH",
  "context": "Remind users about their abandoned cart",
  "tone": "friendly"
}

Response

{ "title": "Forgot something?", "body": "Your cart is waiting — complete your order today!" }

Channels

Configure notification channel settings (push, email, SMS).

GET/api/v1/channels

Get channel configuration

Auth: API Key (secret)

Response

{ "email": { "provider": "POSTALYNK", "configured": true }, "push": { "configured": false }, ... }
PUT/api/v1/channels

Update channel settings

Auth: API Key (secret)

Request Body

{
  "emailProvider": "POSTALYNK",
  "postalynkApiKey": "pk_your_key",
  "postalynkFromEmail": "hello@yourapp.com",
  "fcmServerKey": "your_firebase_server_key",
  "apnsKeyId": "ABC123DEFG",
  "apnsTeamId": "TEAM123456",
  "apnsPrivateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "apnsBundleId": "com.yourapp.ios",
  "apnsEnvironment": "production"
}

Response

{ "updated": true }

Set fcmServerKey for Android/Web push via FCM. Set APNs fields for direct iOS push delivery without Firebase. If APNs is not configured, iOS pushes fall back to FCM (requires APNs cert uploaded to Firebase). Set email fields to configure PostaLynk email delivery.

Push Tokens

Register and manage push notification tokens for users.

POST/api/v1/push-tokens

Register a push token

Auth: API Key (public or secret)

Request Body

{
  "user_id": "user_123",
  "token": "fcm_token_or_web_push_subscription",
  "platform": "IOS"
}

Response

{ "success": true }

Platform must be one of: IOS, ANDROID, WEB. For web, the token is the JSON-stringified PushSubscription object.

DELETE/api/v1/push-tokens

Unregister a push token

Auth: API Key (public or secret)

Request Body

{
  "token": "fcm_token_or_web_push_subscription"
}

Response

{ "success": true }
GET/api/v1/push-tokens

Get VAPID public key for Web Push

Auth: API Key (public or secret)

Response

{ "success": true, "data": { "vapid_public_key": "BLx...", "push_configured": true } }

Use the VAPID public key to create a Web Push subscription in the browser.

Webhooks

Receive real-time event notifications.

POST/api/v1/webhook/:projectId

Webhook endpoint (inbound)

Auth: HMAC-SHA256 signature

Request Body

{
  "event": "message.delivered",
  "data": { "messageId": "msg_1", "userId": "user_123" }
}

Response

{ "received": true }

Verify the X-Signature header using HMAC-SHA256 with your webhook secret.

API Keys

Manage API keys for your project.

GET/api/v1/api-keys

List API keys

Auth: Session (dashboard)

Response

{ "keys": [{ "id": "key_1", "name": "Production", "prefix": "sk_live_abc...", ... }] }
POST/api/v1/api-keys

Create an API key

Auth: Session (dashboard)

Request Body

{ "name": "Production Key", "type": "secret" }

Response

{ "id": "key_1", "key": "sk_live_full_key_shown_once", ... }
DELETE/api/v1/api-keys

Revoke an API key

Auth: Session (dashboard)

Request Body

{ "id": "key_1" }

Response

{ "deleted": true }

Team

Manage team members and invites.

GET/api/v1/team

List team members

Auth: Session (dashboard)

Response

{ "members": [{ "id": "usr_1", "email": "...", "role": "ADMIN" }] }
POST/api/v1/team/invites

Invite a team member

Auth: Session (dashboard)

Request Body

{ "email": "teammate@example.com", "role": "MEMBER" }

Response

{ "invite": { "id": "inv_1", "email": "...", "status": "PENDING" } }

Reports

Retrieve analytics and reporting data.

GET/api/v1/reports

Get analytics report

Auth: API Key (secret)

Query Parameters

range (7d|30d|90d), metrics (events|users|messages)

Response

{ "range": "30d", "events": 12450, "activeUsers": 843, "messagesSent": 2100, ... }