Canonical POP API

Send POP events using the canonical (fixed) schema. Use this endpoint when your events match the standard POP structure.

Endpoint

POST /coatro/v1/pop/events

Description

Send canonical POP events using the fixed schema. You can send a single event or multiple events in one request.

Request Body

{
  "events": [
    {
      "eventId": "string",
      "screenId": "string",
      "siteId": "string",
      "campaignId": "string",
      "creativeId": "string",
      "playedAt": "string",
      "durationMs": 0,
      "impressions": {
        "ageBuckets": {
          "total": 0.0,
          "male": 0.0,
          "female": 0.0
        }
      },
      "context": {},
      "device": {}
    }
  ]
}

Request Schema

Field	Type	Required	Description
events	array	Yes	Array of POP event objects

POP Event Object

Field	Type	Required	Description
eventId	string	No	Unique identifier for the event
screenId	string	No	Identifier for the screen
siteId	string	No	Identifier for the site
campaignId	string	No	Identifier for the campaign
creativeId	string	No	Identifier for the creative
playedAt	string	No	Timestamp when the content was played (ISO 8601 format)
durationMs	integer	No	Duration in milliseconds
impressions	object	No	Impression data with age buckets
context	object	No	Additional context data (any key-value pairs)
device	object	No	Device information (any key-value pairs)

Impressions Object

Field	Type	Description
ageBuckets	object	Age bucket data
ageBuckets.total	number	Total impressions
ageBuckets.male	number	Male impressions
ageBuckets.female	number	Female impressions

Example Request

curl -X POST "http://localhost:8080/coatro/v1/pop/events" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "eventId": "evt-12345",
        "screenId": "screen-001",
        "siteId": "site-001",
        "campaignId": "campaign-001",
        "creativeId": "creative-001",
        "playedAt": "2025-01-27T10:00:00Z",
        "durationMs": 30000,
        "impressions": {
          "ageBuckets": {
            "total": 150.0,
            "male": 80.0,
            "female": 70.0
          }
        }
      }
    ]
  }'

Response

202 Accepted

Your events have been accepted and will be processed.

{
  "message": "Events accepted",
  "acceptedAt": "2025-01-27T10:00:00Z",
  "eventCount": 1
}

Response Schema

Field	Type	Description
message	string	Status message
acceptedAt	string	Timestamp when events were accepted
eventCount	integer	Number of events accepted

Error Responses

• 400 Bad Request - Invalid event data or missing required fields
• 401 Unauthorized - Invalid or missing API key
• 500 Internal Server Error - Server error

INFO

Canonical bulk ingestion endpoints will be available soon for processing large files with canonical POP events.