API Overview

Introduction

Send POP (Proof of Play) events to MeldCX using the Coatro API. You can send events in real-time or batch mode, using either the canonical (fixed) schema or your own flexible schema.

Authentication

All Coatro API requests require authentication. Two methods are supported:

Method 1: Keycloak JWT (recommended for service accounts)

Obtain an access token using the OAuth2 Client Credentials flow (see Authentication Guide), then pass it as a Bearer token:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Your token contains a network_ids claim that scopes access to your networks. The first network in the claim is used by default. For multi-network tokens you can explicitly target a network by name:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-Network-Name: Acme Retail

The network must be authorised by the token.

WARNING

All endpoints require authentication. Requests without valid credentials will receive a 401 Unauthorized response. To get credentials, contact us.

API Endpoints

Canonical POP

• Canonical Events - Send events using the fixed canonical POP schema

Dynamic POP

• Dynamic Events - Send events with your own flexible schema
• Dynamic Bulk Ingestion - Upload and process large files with dynamic POP events

Base URL

https://services-api.viana.ai

Response Codes

Status Code	Description
200	Success
202	Accepted - Your request has been accepted and will be processed
400	Bad Request - Invalid data or missing required fields
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource not found
415	Unsupported Media Type
500	Internal Server Error

Getting Started

1. Get your API key - Contact MeldCX to obtain your API key
2. Choose your endpoint:
   • Use Canonical POP if your data matches the fixed canonical schema
   • Use Dynamic POP if you need to use your own schema
   • Use Dynamic Bulk Ingestion for processing large files
3. Include your API key in every request header
4. Send your events and check the response