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

Submit canonical POP events (real-time or batch). Events are published to GCP Pub/Sub for async processing. Vendor information is automatically derived from the API key used for authentication.

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 (minimum 1 item)

POP Event Object

Field	Type	Required	Description
eventId	string	Yes	Unique identifier for the event
screenId	string	Yes	Identifier for the screen
siteId	string	No	Identifier for the site
campaignId	string	Yes	Identifier for the campaign
creativeId	string	Yes	Identifier for the creative
playedAt	string	Yes	Timestamp when the content was played (minimum length 1; use ISO 8601 format)
durationMs	integer	Yes	Duration in milliseconds
startReason	string	No	Optional reason the playback was initiated (e.g., scheduled, trigger-based)
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

API Base URL: https://services-api.viana.ai

curl -X POST "<API_BASE_URL>/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.