Skip to content

Canonical POP API ​

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

Endpoint ​

http
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 ​

json
{
  "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 ​

FieldTypeRequiredDescription
eventsarrayYesArray of POP event objects (minimum 1 item)

POP Event Object ​

FieldTypeRequiredDescription
eventIdstringYesUnique identifier for the event
screenIdstringYesIdentifier for the screen
siteIdstringNoIdentifier for the site
campaignIdstringYesIdentifier for the campaign
creativeIdstringYesIdentifier for the creative
playedAtstringYesTimestamp when the content was played (minimum length 1; use ISO 8601 format)
durationMsintegerYesDuration in milliseconds
startReasonstringNoOptional reason the playback was initiated (e.g., scheduled, trigger-based)
impressionsobjectNoImpression data with age buckets
contextobjectNoAdditional context data (any key-value pairs)
deviceobjectNoDevice information (any key-value pairs)

Impressions Object ​

FieldTypeDescription
ageBucketsobjectAge bucket data
ageBuckets.totalnumberTotal impressions
ageBuckets.malenumberMale impressions
ageBuckets.femalenumberFemale impressions

Example Request ​

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

bash
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.

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

Response Schema ​

FieldTypeDescription
messagestringStatus message
acceptedAtstringTimestamp when events were accepted
eventCountintegerNumber 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.