CDP Events Endpoint - Client Integration Guide (TVM-1727)

CDP-Events-Endpoint-Guide.md

CDP Events Endpoint - Client Integration Guide

Endpoint

Development:

POST https://playtv-api.forte.ws/v1/events

Production: (coming soon)

POST https://playtv-api.parlor.com/v1/events

Authentication

Use the X-Events-Key header (no Bearer token required):

X-Events-Key: <api-key-from-backend-team>

Request Format

{
  "events": [{
    "event_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_type": "post.view",
    "tenant_id": 1,
    "source": {
      "platform": "ios",
      "device_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
      "app_version": "2.1.0",
      "os_version": "17.2"
    },
    "subject": {
      "type": "post",
      "id": "01HQXYZ123"
    },
    "context": {
      "custom_field": "any extra data"
    }
  }]
}

Required Fields

Field	Type	Description
event_id	UUID v4	Client-generated unique ID
event_type	string	e.g., post.view, video.play, notification.click
tenant_id	int	1 = Parlor, 2 = PlayTV
source.platform	enum	ios, android, web, tv
source.device_id	string	Persistent device UUID

Optional Fields

• source.app_version, source.os_version, source.device_model
• subject.type, subject.id - what the event is about
• context - any additional event-specific data
• occurred_at - ISO 8601 timestamp (defaults to server time)

Responses

Code	Response	Meaning
202	{"success": true}	Event accepted
401	{"success": false, "error": "Invalid or missing API key"}	Bad/missing X-Events-Key
422	Validation errors	Missing required fields
429	{"success": false, "error": "Too many requests"}	Rate limited

Rate Limits

• Per device: 120 requests/minute (based on device_id + tenant_id + platform)
• Per IP fallback: 20 requests/minute

Batching

Events array supports multiple events per request - batch events every 5-10 seconds instead of sending individually.

Example: curl (Development)

curl -X POST https://playtv-api.forte.ws/v1/events \
  -H "Content-Type: application/json" \
  -H "X-Events-Key: <your-api-key>" \
  -d '{
    "events": [{
      "event_id": "550e8400-e29b-41d4-a716-446655440000",
      "event_type": "post.view",
      "tenant_id": 1,
      "source": {
        "platform": "ios",
        "device_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
      },
      "subject": {
        "type": "post",
        "id": "01HQXYZ123"
      }
    }]
  }'

Contact

For the API key, contact the backend team.