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.

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

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

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

Events4Users4Segments5Automations4Campaigns4Templates4Messages2News Feed4AI Content1Channels2Webhooks1API Keys3Team2Reports1

Events

Track and query user events.

POST/api/v1/events

Track an event

Auth: API Key (public or secret)

Request Body

{
  "userId": "user_123",
  "eventName": "purchase",
  "properties": {
    "amount": 49.99,
    "product_id": "prod_1"
  }
}

Response

{ "id": "evt_abc123", "status": "ok" }
GET/api/v1/events

List events

Auth: API Key (secret)

Query Parameters

userId, eventName, from, to, page, limit

Response

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

Get a single event

Auth: API Key (secret)

Response

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

Delete an event

Auth: API Key (secret)

Response

{ "deleted": true }

Users

Manage end-user profiles and properties.

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"
}

Response

{ "updated": true }

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, ... }