API Philosophy & Design Principles

API Philosophy & Design Principles

What is the Cenareo Management API?

The Cenareo Management API is your programmatic gateway to the complete digital signage platform. It enables you to automate every aspect of campaign management and fleet operations that you would normally perform through our web interface—and much more.

Campaign & Content Automation

Create, schedule, and manage advertising campaigns programmatically. Upload media files, define broadcast schedules with precise time periods, and deploy content across your screen network—all without touching the web interface. Whether you're running a simple campaign on a few screens or orchestrating complex multimedia campaigns across thousands of locations, the API handles it seamlessly.

Fleet Management at Scale

Monitor and control your entire screen inventory. Track screen status and health in real-time, manage player stock and deployments, update screen configurations, and organize locations with place management. From activation and deactivation to opening hours and technical specifications, every aspect of your fleet is accessible via API.

For networks with multiple advertisers, manage screen time allocation programmatically. Configure and monitor share of voice quotas between lessors and advertisers, ensuring fair distribution of broadcast time across your network while maintaining full visibility into quota usage.

Integration-First Design

Built for system integrations, the API allows you to connect Cenareo with your existing tools—CMS platforms, inventory systems, scheduling software, or custom dashboards. Automate content publishing workflows, synchronize campaign data with external systems, and build custom monitoring solutions tailored to your operational needs.

In essence, if you can do it on the Cenareo platform, you can do it through the API—often more efficiently and at scale.

Ready to dive into technical details? See the complete API documentation for endpoints, parameters, and code examples.

Why Use the API?

The Management API transforms how you operate your digital signage network by enabling automation, scale, and efficiency that's difficult through manual web interface interactions.

Automation & Integration

Eliminate repetitive manual tasks by connecting Cenareo directly to your existing systems. Automatically publish content when it's approved in your CMS, synchronize campaign schedules with your marketing calendar, or trigger emergency alerts from your monitoring systems. The API enables seamless workflows between Cenareo and your business tools, reducing human error and freeing your team to focus on strategy rather than execution.

Scale & Bulk Operations

Managing hundreds or thousands of screens through a web interface becomes impractical. The API allows you to perform bulk operations effortlessly—update opening hours across an entire city's screens, deploy campaigns to regional groups, or reconfigure network-wide settings with a single script. What would take hours of clicking becomes seconds of code execution.

Performance & Parallel Processing

The API's asynchronous architecture enables true parallelism. Create multiple campaigns simultaneously, update dozens of screens in parallel, and manage multiple operations concurrently—all without waiting for each task to complete. Launch a 100-screen campaign deployment while simultaneously updating screen configurations across your fleet. The webhook-driven model means your application remains responsive, handling multiple operations efficiently without blocking or timeouts.

Real-Time Monitoring & Response

Webhooks provide instant notifications of operation completion, enabling real-time dashboards and immediate error handling. Build custom monitoring solutions that alert you instantly when campaigns fail to deploy, track operation status across your entire workflow, and maintain complete visibility into your network's state—all without polling or manual checking.

In short: the API enables the speed, scale, and automation required for modern digital signage operations. What takes hours manually takes seconds programmatically.

Data Model & Relationships

Understanding the Core Objects

The Cenareo platform is built around five core objects that work together to deliver content to screens. Understanding how these objects relate to each other is essential for effective API usage.

Object Hierarchy

Fleet (Your Organization)
  │
  ├── Places (Physical Locations)
  │     └── Screens (Display Devices)
  │           └── Players (Hardware Units)
  │
  ├── Media (Content Files)
  │
  └── Campaigns (Ads)
        └── Broadcasts (Content-to-Screen Mapping)
              ├── Links to Media
              └── Links to Screens

Core Objects Philosophy

Campaign: The Semantic Container

Philosophical Purpose:

A campaign represents a meaningful business initiative with coherent content and temporal boundaries.

Think of a campaign as the answer to: "What marketing or communication effort am I running?"

Examples of good campaign semantics:

"Summer Sale 2025" — Groups all summer promotional content, runs June-August
"New Product Launch Q4" — Groups product introduction media, runs during launch period
"Holiday Greetings December" — Seasonal messaging with clear start/end dates
"Store Hours Update" — Permanent informational content (no end date)

What makes a good campaign:

Semantic coherence: All content relates to the same business purpose
Temporal logic: Start and end dates reflect the campaign's real-world timeline
Unified management: Content that should be activated/paused together belongs together

Key attributes:

name: Campaign identifier
campaign_startdate / campaign_enddate: Temporal boundaries
status: active (running) or suspended (paused)
campaign_type: standard, solo, event, or HTML screenshot

Relationships:

Contains one or more Broadcasts
Can be displayed on multiple Screens (via broadcasts)

Broadcast: The Scheduling Instruction

Philosophical Purpose:

A broadcast is a calendaring instruction that says "Display this media on these screens during these time periods."

Think of a broadcast as an entry in a scheduling calendar, not a playlist item.

The broadcast defines: - WHAT: Which media to display (media) - WHERE: Which screens to display it on (screens) - WHEN: Time-based scheduling rules (display_periods)

Critical concept:

Cenareo does NOT use manual playlists. The player automatically builds its playback loop based on all active broadcasts for that screen. You don't create a "Monday playlist" and a "Tuesday playlist"—instead, you create broadcasts with temporal rules, and the player intelligently constructs the appropriate loop for each time period.

Key attributes:

media: URL of the media to display
screens: Array of screen URLs where this content plays
display_periods: Time-based scheduling (hours/days)
screens_loop_indexes: Precise loop positioning per screen

Relationships:

Belongs to one Campaign
References one Media
References multiple Screens

Media: The Content Asset

Philosophical Purpose:

Media is your reusable content asset—the actual file (image, video, PDF) that gets displayed.

Content lifecycle philosophy:

Media files are content library items, independent of campaigns
One media can be reused across multiple campaigns and broadcasts
Media should represent atomic content units (one image, one video, one document)

Key attributes:

type: picture, video, or pdf
display_time: Duration for images/PDFs (videos use file duration)
url_origin: Source URL for remote content
refresh_time: Auto-update interval (for URL-based media)

Creation methods:

Upload file directly
Provide URL (we download it)
Provide URL with auto-refresh (dynamic content)

Screen: The Physical Display

Philosophical Purpose:

A screen represents a physical display device in a specific location, with its own operational characteristics.

Identity philosophy: Each screen is a unique entity with:

Geographic identity: Where it's located (place)
Operational identity: When it's on (opening_hours), its status (active)
Technical identity: Display type, resolution, capabilities
Business identity: Share of voice allocations (allocated_times)

Key attributes:

name: Human-readable identifier
slug: URL-friendly identifier
active: Operational status
place: Associated physical location
opening_hours: When the screen is on
allocated_times: Share of voice quotas (if applicable)

Relationships:

Belongs to a Place
Has one Player (hardware)
Displays content from Broadcasts
Member of Screen Groups (optional)

Management operations:

Activate/deactivate
Update configuration
Set operating hours
Assign to location

Place: The Physical Location

Philosophical Purpose: A place represents a physical location where screens are installed—a store, a building, a venue.

Key attributes:

name: Location name
address, city, postalcode, country: Geographic details
location: Latitude/longitude
exclusive_fleet: Set if private to your fleet
private_fleet_key: Your custom identifier

Types:

Public places: Shared across fleets, immutable
Private places: Exclusive to your fleet, fully manageable

Relationships:

Contains multiple Screens
Belongs to a Fleet

Complete Tutorial: Your First Campaign

Goal

Create a simple campaign that displays a promotional image on three screens for one week.

Prerequisites

Valid API authentication token
Three screens in your fleet
One promotional image file

Step 1: Get Your Authentication Token

import requests

# Request JWT token
response = requests.post(
    'https://manage.cenareo.com/api/get_jwt_token/',
    json={
        'username': 'your_username',
        'password': 'your_password'
    }
)

token = response.json()['token']
headers = {'Authorization': f'JWT {token}'}

print("✓ Token obtained")

What happened: You exchanged your credentials for a JWT token that you'll use for all subsequent requests.

Step 2: Find Your Screens

# List your screens
response = requests.get(
    'https://manage.cenareo.com/api/management/v3/screens/',
    headers=headers
)

screens = response.json()['results']

# Select first three screens
screen_urls = [screen['url'] for screen in screens[:3]]

print(f"✓ Found {len(screens)} screens")
print(f"✓ Selected 3 screens: {[s['name'] for s in screens[:3]]}")

What happened: You retrieved your screen inventory and selected three screens for your campaign.

Tip: You can filter screens by location:

# Get only Paris screens
response = requests.get(
    'https://manage.cenareo.com/api/management/v3/screens/?city=Paris',
    headers=headers
)

Step 3: Upload Your Media

# Upload promotional image
with open('summer_sale.jpg', 'rb') as f:
    response = requests.post(
        'https://manage.cenareo.com/api/management/v3/medias/',
        headers=headers,
        files={'file': f},
        data={'display_time': 15}  # Display for 15 seconds
    )

media_url = response.json()['url']
media_id = response.json()['id']

print(f"✓ Media uploaded: {media_id}")
print(f"✓ Media URL: {media_url}")

What happened: You uploaded your image to Cenareo. The system assigned it a unique URL that you'll use to reference it.

Note: For videos, omit display_time (automatically detected from video duration).

Step 4: Create Your Campaign

from datetime import datetime, timedelta

# Calculate dates
start_date = datetime.now().date()
end_date = (datetime.now() + timedelta(days=7)).date()

# Create campaign payload
campaign_payload = {
    'name': 'Summer Sale 2025',
    'campaign_startdate': start_date.isoformat(),
    'campaign_enddate': end_date.isoformat(),
    'broadcasts': [
        {
            'media': media_url,
            'screens': screen_urls
        }
    ],
    'webhook_url': 'https://your-domain.com/webhook',
}

# Send create request
response = requests.post(
    'https://manage.cenareo.com/api/management/v3/ads/',
    headers=headers,
    json=campaign_payload
)

task_id = response.json()['task_id']

print(f"✓ Campaign creation started")
print(f"✓ Task ID: {task_id}")
print("  Waiting for webhook notification...")

What happened: - You created a campaign scheduled for one week - The request returned immediately with a task_id - Processing happens in the background - Your webhook will be called when complete

Step 6: Handle the Webhook Response

Your webhook endpoint will receive this payload when the campaign is ready:

{
  "campaign_url": "https://manage.cenareo.com/api/management/v3/ads/campaign-uuid-here/",
  "campaign_id": "campaign-uuid-here",
  "campaign_name": "Summer Sale 2025", 
  "user_id": "your-user-username-here",
  "status": "created"
}

What's Next?

Now that you've created your first campaign, explore:

More scheduling options:

Time-based display periods (show only during business hours)
Loop positioning (control exact playback order)
Campaign types (solo, event, HTML)

Advanced workflows:

Update existing campaigns
Create multimedia campaigns
Manage campaign lifecycle
A/B testing with different content

Fleet management:

Monitor screen health
Update screen configuration
Manage places and locations

API Philosophy & Design Principles

What is the Cenareo Management API?

Campaign & Content Automation

Fleet Management at Scale

Share of Voice Control

Integration-First Design

Why Use the API?

Automation & Integration

Scale & Bulk Operations

Performance & Parallel Processing

Real-Time Monitoring & Response

Data Model & Relationships

Understanding the Core Objects

Object Hierarchy

Core Objects Philosophy

Campaign: The Semantic Container

Broadcast: The Scheduling Instruction

Media: The Content Asset

Screen: The Physical Display

Place: The Physical Location

Complete Tutorial: Your First Campaign

Goal

Prerequisites

Step 1: Get Your Authentication Token

Step 2: Find Your Screens

Step 3: Upload Your Media

Step 4: Create Your Campaign

Step 6: Handle the Webhook Response

What's Next?