Trillboards DOOH Advertising

[AdCP Signals] Activate an audience signal for DSP targeting.

Generates IAB Audience Taxonomy 1.1 segment parameters that DSPs can use in bid requests. Returns an activation_key token for referencing this signal activation.

WHEN TO USE:

• Converting audience signals into actionable targeting parameters

• Generating IAB segment IDs for programmatic bid requests

• Creating reusable targeting configurations

RETURNS:

• activation_key: Token for referencing this activation (24h expiry)

• targeting: { iab_segments, iab_taxonomy_version, custom_params }

• screen_count, provider, data_source, methodology

EXAMPLE: User: "Activate high-income professional targeting on my retail screens" activate_signal({ signal_type: "audience", parameters: { income: "high", lifestyle: "professional" }, screen_ids: ["507f1f77bcf86cd799439011"] })

Record multiple impressions in a single request (up to 100).

WHEN TO USE:

• Bulk reporting impressions from offline period

• Efficient batch processing of impressions

• When device was offline and needs to sync

RETURNS:

• success: Boolean indicating success

• processed: Number of impressions processed

• failed: Number of failed impressions

• total_earnings: Total earnings credited

• errors: Any error details for failed impressions

EXAMPLE: User: "Sync the last hour of impressions" batch_impressions({ impressions: [ { fingerprint: "P_abc123", ad_id: "507f1f77bcf86cd799439011", duration_seconds: 15 }, { fingerprint: "P_abc123", ad_id: "507f1f77bcf86cd799439012", duration_seconds: 10 } ] })

Create a new advertising campaign targeting DOOH screens.

WHEN TO USE:

• Setting up a new ad campaign on Trillboards screens

• Targeting specific venues, locations, or audience profiles

• Allocating budget for programmatic DOOH buys

RETURNS:

• campaign_id: Unique campaign identifier (UUID)

• name, status, budget, screen_count, dates

Campaign starts in "draft" status. Use update_campaign to set status to "active".

EXAMPLE: User: "Create a campaign targeting retail screens in NYC at $5 CPM" create_campaign({ name: "NYC Retail Q1", budget_cpm: 5.0, daily_budget_usd: 100, venue_types: ["retail"], targeting: { geo: { city: "New York", state: "NY" } }, creative_url: "https://cdn.example.com/ad.mp4", start_date: "2026-03-01", end_date: "2026-03-31" })

Create an incrementality experiment for a campaign.

Sets up a geo-holdout, ghost ads, or propensity score matching experiment to causally measure DOOH advertising lift.

WHEN TO USE:

• Setting up a new A/B test before or during a campaign

• Defining treatment and control DMAs for geo-holdout tests

• Configuring experiment parameters (holdout %, MDE, power)

RETURNS: The created experiment object with experiment_id, status, and all parameters.

EXAMPLE: create_experiment({ campaign_id: "camp_abc123", experiment_type: "geo_holdout", treatment_dmas: ["501", "504"], control_dmas: ["503", "505"], holdout_pct: 0.15, target_mde: 0.10 })

[AdCP Media Buy] Create a media buy (campaign) from an AdCP buy specification.

Creates a campaign that targets DOOH screens based on the provided specification. Returns a media_buy_id for tracking and a creative_deadline for asset submission.

WHEN TO USE:

• Executing a programmatic DOOH buy via an AI agent

• Creating campaigns from DSP trading desk agents

• Automated media buying workflows

RETURNS:

• media_buy_id: Unique identifier for this media buy

• campaign_id: Internal campaign identifier

• creative_deadline: Deadline for creative asset submission

• targeting_summary: What was targeted

• budget_summary: Budget allocation details

EXAMPLE: User: "Buy retail screens in NYC at $5 CPM for next week" create_media_buy({ name: "NYC Retail Week 12", buy_spec: { venue_types: ["retail"], geo: { city: "New York", state: "NY" }, budget: { daily_usd: 500, bid_cpm: 5.0 }, schedule: { start_date: "2026-03-16", end_date: "2026-03-22" } }, creative: { url: "https://cdn.example.com/creative.mp4", type: "video", duration_seconds: 15 }, buyer_ref: "agency-order-12345" })

Create a new webhook subscription for real-time events.

WHEN TO USE:

• Setting up real-time notifications for device events

• Integrating with external systems

• Monitoring ad playback and impressions

AVAILABLE EVENTS:

• device.online: When a device comes online

• device.offline: When a device goes offline

• impression.recorded: When an impression is logged

• campaign.allocated: When a campaign is allocated to a device

• payout.processed: When a payout is processed

• programmatic.ad_started: When a programmatic ad begins playing

• programmatic.ad_ended: When a programmatic ad finishes playing

• programmatic.no_fill: When a programmatic ad request gets no fill

• programmatic.error: When a programmatic ad request errors

RETURNS:

• webhook_id: Unique webhook identifier

• url: The webhook endpoint URL

• events: Subscribed events

• secret: HMAC signing secret (if provided)

• status: enabled/disabled

EXAMPLE: User: "Set up a webhook for device status changes" create_webhook({ url: "https://api.mycompany.com/trillboards/webhooks", events: ["device.online", "device.offline", "programmatic.error"], secret: "my-signing-secret-123" })

Soft-delete a device from the partner account.

WHEN TO USE:

• Removing a device that's been decommissioned

• Cleaning up test devices

• Removing a device that's been relocated to another partner

RETURNS:

• success: Boolean indicating success

• device_id: The deleted device ID

• message: Confirmation message

EXAMPLE: User: "Remove the old lobby kiosk" delete_device({ device_id: "lobby-kiosk-old" })

Delete a webhook subscription.

WHEN TO USE:

• Removing a webhook that's no longer needed

• Cleaning up old integrations

• Removing test webhooks

RETURNS:

• success: Boolean indicating success

• webhook_id: The deleted webhook ID

• message: Confirmation message

EXAMPLE: User: "Delete the old webhook" delete_webhook({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d" })

Send a heartbeat signal from a device to report its status.

WHEN TO USE:

• Regular device health monitoring (every 30-60 seconds)

• Reporting current playback status

• Reporting errors or issues

RETURNS:

• success: Boolean indicating success

• device_status: Current device status in system

• next_heartbeat_seconds: Recommended interval for next heartbeat

EXAMPLE: User: "Send heartbeat for device P_abc123" device_heartbeat({ fingerprint: "P_abc123", status: "playing", current_ad_id: "507f1f77bcf86cd799439011", uptime_seconds: 3600 })

Discover available DOOH screens in the Trillboards network.

WHEN TO USE:

• Finding screens by venue type (retail, transit, office, etc.)

• Finding screens in a specific city/state or within a radius

• Finding screens with a specific audience profile (high income, professionals, etc.)

• Getting an overview of available inventory with live audience data

RETURNS:

• screens: Array of screen objects with location, venue type, online status, and live audience data

• total: Total matching screens

• online_count: Number of currently online screens

Each screen includes real-time audience data when available:

• face_count, attention_score, income_level, mood, lifestyle

• purchase_intent, crowd_density, ad_receptivity, dwell_time

EXAMPLE: User: "Find retail screens in New York with high-income audience" discover_inventory({ venue_types: ["retail"], location: { city: "New York", state: "NY" }, audience_profile: { income: "high" }, limit: 20 })

Export exposed audience cohort to a DSP for retargeting.

Pushes MAID hashes from the campaign's exposed cohort to the specified DSP (The Trade Desk, DV360, or Meta). Creates or reuses a DSP segment.

WHEN TO USE:

• Activating DOOH-exposed audiences for retargeting on digital channels

• Pushing cohorts to TTD, DV360, or Meta Custom Audiences

• Measuring cross-channel retargeting lift

RETURNS:

• status: 'synced', 'no_cohort', 'credentials_missing', or 'empty_cohort'

• destination: the DSP name

• segmentId: internal segment ID

• externalSegmentId: DSP-side segment ID

• maidCount: number of MAIDs uploaded

• accepted: number accepted by DSP

Supported destinations: ttd, dv360, meta, cadent, mediaocean

EXAMPLE: export_cohort({ campaign_id: "camp_abc123", destination: "ttd" })

[AdCP] Get Trillboards AdCP capabilities and supported protocols.

Returns the full capability declaration for Trillboards as an AdCP DOOH seller agent. This tool does NOT require authentication.

WHEN TO USE:

• Discovering what protocols Trillboards supports (Signals, Media Buy)

• Understanding available audience signals and data methodology

• Getting MCP endpoint and discovery URLs

RETURNS:

• supported_protocols: ['signals', 'media_buy']

• inventory: DOOH format details, network size

• audience_data: signal list, methodology, refresh rate

• pricing: model, currency, floor CPM

• discovery: well_known_url, mcp_endpoint

Get analytics data for the partner account.

WHEN TO USE:

• Viewing overall performance metrics

• Analyzing device performance

• Generating reports on impressions and earnings

• Comparing performance over time periods

RETURNS:

• summary: Overall stats (impressions, earnings, active_devices)

• time_series: Data points over time

• top_devices: Best performing devices

• breakdown: Data grouped by requested dimension

EXAMPLE: User: "Show me last week's analytics by device" get_analytics({ start_date: "2026-01-01", end_date: "2026-01-07", group_by: "device" })

User: "Get monthly performance breakdown" get_analytics({ start_date: "2025-12-01", end_date: "2025-12-31", group_by: "day" })

Get edge AI attention metrics for a campaign (FEIN-powered).

This is what makes DOOH attribution better than digital: Trillboards MEASURES viewability via FEIN edge AI instead of estimating it.

WHEN TO USE:

• Measuring actual human attention to ads (not just impressions)

• Comparing attention-adjusted CPM (aCPM) vs standard CPM

• Getting face count, dwell time, and emotion engagement data

RETURNS:

• impressions: total, uniqueDevices

• attention: avgScore (0-1), medianScore, p90Score, avgDwellSeconds, avgFaceCount, qualifiedPct

• economics: standardCpm, attentionCpm (aCPM), costPerAttentiveReach

• emotion: avgEngagement (0-1), positiveEmotionPct

aCPM = total_media_cost / (SUM(attention_score * face_count) / 1000)

Get daily attribution timeseries for a campaign.

WHEN TO USE:

• Tracking attribution trends over time

• Identifying which days had the strongest lift

• Building attribution dashboards with daily granularity

RETURNS: Array of daily data points, each with:

• date, uniqueDevices, totalExposures, avgFrequency

• exposedVisitors, controlVisitors, liftPct, incrementalVisits

• costPerVisit, totalMediaCost, isSignificant

EXAMPLE: get_attribution_timeseries({ campaign_id: "camp_abc123", start_date: "2026-03-01", end_date: "2026-03-10" })

Predict what the audience will look like at a screen at a specific time.

WHEN TO USE:

• Planning campaigns for specific time slots

• Estimating audience composition before buying

• Comparing audience at different times of day

Uses historical audience data to predict typical audience patterns.

RETURNS:

• predicted_face_count: Expected number of viewers

• predicted_attention: Expected attention score

• typical_income: Most common income level at that time

• typical_lifestyle: Most common lifestyle segment at that time

• confidence: Prediction confidence (0-1, based on sample count)

• sample_count: Number of historical data points used

EXAMPLE: User: "What's the typical audience at this screen on Monday at 3pm?" get_audience_forecast({ screen_id: "507f1f77bcf86cd799439011", hour: 15, day: 1, lookback_days: 30 })

Find screens with similar audience profiles using pgvector similarity.

Uses 64-dimensional audience vectors with HNSW cosine similarity index to find screens whose audience demographics, attention, and behavioral patterns match a target screen.

WHEN TO USE:

• Expanding campaign reach to screens with similar audiences

• Finding new inventory that matches a high-performing screen

• Building lookalike audience segments for targeting

RETURNS: Array of similar screens ranked by cosine similarity, each with:

• screen_id, similarity (0-1), metadata (face_count, attention, income, lifestyle), last_seen

EXAMPLE: get_audience_lookalike({ screen_id: "scr_abc123", limit: 10, min_similarity: 0.8 })

Check current billing status including whether billing is set up, credit balance, Stripe customer ID, and payment method status. Use this to determine if billing setup is needed before making paid API calls.

Get comprehensive attribution summary for a DOOH campaign.

WHEN TO USE:

• Measuring overall campaign effectiveness (reach, footfall, sales lift)

• Getting a high-level view of campaign attribution metrics

• Checking statistical significance of attribution results

RETURNS:

• reach: uniqueDevices, totalImpressions, avgFrequency

• footfall: exposedVisitors, controlVisitors, incrementalLiftPct, incrementalVisits

• cost: totalMediaCost, costPerUniqueReach, costPerIncrementalVisit

• quality: avgMatchConfidence, statisticalSignificance, isSignificant

• dataFreshness: latestOutcomeAt, provisionalCount, finalizedCount

Returns null if no attribution data exists for the campaign.

Get geographic exposure heatmap data for a campaign.

Returns lat/lng clusters with exposure counts and device reach, useful for visualizing where ads were shown on a map.

WHEN TO USE:

• Visualizing campaign geographic coverage

• Identifying hotspots of ad exposure

• Analyzing geographic distribution of attributed foot traffic

RETURNS: Array of geographic clusters (max 500), each with:

• lat, lng (rounded to 3 decimal places)

• uniqueDevices, totalExposures

• avgConfidence (match confidence score)

Get detailed performance metrics for a campaign.

WHEN TO USE:

• Monitoring active campaign performance

• Reviewing completed campaign results

• Getting per-screen impression breakdowns

RETURNS:

• campaign_id, name, status, budget, dates

• performance: impressions, spend_estimate_usd, avg_cpm, unique_screens, avg_latency_ms

• screen_breakdown: per-screen impressions and CPM

EXAMPLE: User: "How is my NYC retail campaign performing?" get_campaign_performance({ campaign_id: "550e8400-e29b-41d4-a716-446655440000" })

Get per-creative attention breakdown for a campaign.

WHEN TO USE:

• A/B testing creative variants by attention score

• Identifying which creative drives the most engagement

• Comparing aCPM across creative assets

RETURNS: Array of creatives ranked by attention score, each with:

• creativeId, totalImpressions, uniqueDevices

• avgAttentionScore (0-1), avgDwellSeconds, avgFaceCount

• attentionCpm, avgEmotionEngagement, positiveEmotionPct, attentionQualifiedPct

Get attribution performance by individual creative variant.

Links creative execution to attribution outcomes: which creative variant drove the most store visits?

WHEN TO USE:

• Comparing creative A/B/C test performance on attribution outcomes

• Finding the optimal creative x venue_type x daypart x weather combination

• Identifying the creative with the highest visit rate

RETURNS: Array of creatives ranked by store visits, each with:

• creativeId, variant, totalVisits, avgVisitRate

• attention: avgScore, avgDwell, avgEmotion, dominantEmotion

• avgLiftPct, avgCostPerVisit

• bestContext: { venueType, daypart, weather }

• dateRange: { first, last, daysMeasured }

Get cross-channel customer journey data (Sankey flow) for a campaign.

Shows how users flow between channels: DOOH -> mobile -> web -> store.

WHEN TO USE:

• Visualizing the customer journey across DOOH and digital channels

• Understanding channel transition patterns

• Building Sankey diagrams of marketing funnels

RETURNS:

• flows: Array of { source, target, count } transitions between channels

• channels: Array of { channel, touchpoints, uniqueDevices } distribution

Get detailed information about a specific device.

WHEN TO USE:

• Checking status of a single device

• Getting device configuration details

• Debugging device issues

RETURNS:

• device_id: Your internal device ID

• trillboards_device_id: Internal Trillboards ID

• fingerprint: Device fingerprint

• name: Device name

• status: online/offline

• last_seen: Last heartbeat timestamp

• location: Location details

• specs: Device specifications

• stats: Impression and earnings stats

EXAMPLE: User: "Get details for vending machine 001" get_device({ device_id: "vending-001-nyc" })

Get current ads scheduled for a device (for testing).

WHEN TO USE:

• Testing device ad delivery

• Debugging which ads are being shown

• Verifying ad targeting is working

RETURNS:

• ads: Array of advertisement objects

• default_stream: Default content when no ads

• schedule: Current ad schedule

EXAMPLE: User: "What ads are showing on device P_abc123?" get_device_ads({ fingerprint: "P_abc123" })

Get incrementality/lift test results for a campaign.

Uses Bayesian (Beta-Binomial with 10K Monte Carlo samples) and frequentist (chi-square with Yates correction) methods for causal measurement.

WHEN TO USE:

• Proving causal DOOH advertising effectiveness

• Getting both Bayesian and frequentist significance measures

• Seeing treatment vs control group visit rates and lift

RETURNS: Array of experiments, each with:

• experimentId, type (geo_holdout/ghost_ads/psm), status

• treatmentDmas, controlDmas

• latestResult: treatment/control rates, lift%, incrementalVisits, pValue, posteriorProbPositive, expectedUplift, credibleInterval

Returns empty array if no experiments exist for this campaign.

Get real-time audience data for a specific screen.

WHEN TO USE:

• Checking current audience at a screen before buying

• Monitoring audience during a live campaign

• Getting detailed audience signals (attention, mood, purchase intent, demographics)

RETURNS real-time data from edge AI sensors (refreshed every 10 seconds):

• face_count: Number of people currently viewing

• attention_score: How attentively the audience is watching (0-1)

• income_level: Estimated income bracket (from Gemini Vision)

• mood: Current audience mood

• lifestyle: Primary lifestyle segment

• purchase_intent: Purchase intent level

• crowd_density: Estimated venue occupancy

• ad_receptivity: How receptive the audience is to ads (0-1)

• emotional_engagement: Emotional engagement score (0-1)

• group_composition: Solo/couples/families/friends/work groups

• signals_age_ms: How fresh the data is in milliseconds

EXAMPLE: User: "What's the current audience at screen 507f1f77bcf86cd799439011?" get_live_audience({ screen_id: "507f1f77bcf86cd799439011" })

[AdCP Media Buy] Get delivery/performance report for a media buy.

Returns campaign performance with breakdowns by screen, venue, hour, and audience segment.

WHEN TO USE:

• Monitoring campaign delivery in real-time

• Getting performance breakdowns for optimization

• Reporting on campaign results

RETURNS:

• delivery: impressions, spend, avg_cpm, unique_screens, fill_rate

• breakdowns: by_screen, by_venue, by_hour (top performers)

EXAMPLE: get_media_buy_delivery({ media_buy_id: "mbuy_abc123" })

Get multi-touch attribution model results for a campaign.

Supported models: time_decay, position_based, attention_weighted.

WHEN TO USE:

• Understanding how DOOH fits into the full marketing funnel

• Seeing credit allocation across DOOH, mobile, web, and store channels

• Quantifying DOOH's contribution to conversions

RETURNS:

• totalChains: number of multi-touch journeys found

• avgTouchpoints: average touchpoints per chain

• channelAttribution: { dooh, mobile, web, store } (each 0-1, sums to 1)

• conversions: total conversion events

• totalConversionValue: sum of conversion values (cents)

• avgConfidence: average match confidence across chains

Returns null if no multi-touch chains exist.

Get network-wide statistics across all partner screens.

WHEN TO USE:

• Getting a high-level overview of network performance

• Checking how many screens are online

• Reviewing total impressions and revenue estimates

RETURNS:

• total_screens, online_screens

• impressions, total_auctions

• revenue_estimate_usd, avg_cpm, fill_rate

EXAMPLE: User: "How is my network performing this week?" get_network_stats({ time_range: "7d" })

Get information about the authenticated partner account.

WHEN TO USE:

• Checking current partner status and stats

• Verifying API key is working

• Getting partner account details

RETURNS:

• partner_id: Partner identifier

• company_name: Registered company name

• status: Account status (active, suspended, etc.)

• device_count: Number of registered devices

• total_impressions: Lifetime impression count

• earnings: Earnings summary

EXAMPLE: User: "What's my partner account status?" get_partner_info({})

Get machine-readable pricing for all Trillboards products. Returns graduated usage-based pricing, free tier thresholds, and committed-use discount tiers. No authentication required — use this to evaluate costs before integrating.

[AdCP Media Buy] Get available DOOH advertising products and packages.

Returns DOOH screen packages organized by venue type, location, and audience profile, with real-time pricing based on current demand and audience quality.

WHEN TO USE:

• Browsing available inventory before creating a campaign

• Comparing pricing across venue types and locations

• Understanding what's available in a specific market

RETURNS:

• products: Array of product packages with pricing, reach, and audience data

• Each product includes: name, venue_type, screen_count, pricing, avg_audience

EXAMPLE: User: "What DOOH products are available in NYC?" get_products({ market: "New York", venue_types: ["retail", "transit"] })

Get Return on Ad Spend (ROAS) with transaction attribution data.

Closes the ROAS loop: matches purchase events to DOOH exposures with time-decay weighting, and computes attributed revenue and incremental ROAS.

WHEN TO USE:

• Measuring revenue directly attributable to DOOH advertising

• Getting ROAS and incremental ROAS (iROAS) figures

• Seeing sales lift between exposed and control groups

RETURNS:

• transactions: total, uniquePurchasers, totalRevenueCents, avgBasketCents

• attribution: attributedTransactions, attributedRevenueCents, totalMediaCostCents, roas, iroas

• salesLift: exposedPurchasers, controlPurchasers, incrementalTransactions, incrementalRevenueCents, salesLiftPct, posteriorProbPositive

• timing: avgHoursToPurchase, medianHoursToPurchase

Returns null if no transaction data exists.

[AdCP Signals] Get real-time audience signals from DOOH screens.

This is an AdCP (Ad Context Protocol) compliant tool. It returns deterministic audience signals captured by edge AI (vision + audio + speech) on Trillboards screens.

WHEN TO USE:

• Discovering available audience signals before buying inventory

• Evaluating audience composition at specific venues or locations

• Building targeting segments based on real-time audience data

Unlike probabilistic data, Trillboards signals are DETERMINISTIC — captured by on-device cameras and microphones, analyzed by ML Kit and Gemini Vision.

RETURNS:

• signals: Array of per-screen signal objects with demographics, venue, behavior, geo

• metadata: total_screens, matching_screens, screens_with_live_data

EXAMPLE: User: "What audience signals are available at retail locations?" get_signals({ signal_spec: { signal_types: ["demographics", "behavior"], filters: { venue_type: "retail" } } })

Get your current billing period usage summary with per-product breakdown and costs. Shows free tier consumption, paid usage, and total cost.

Get delivery history for a webhook.

WHEN TO USE:

• Debugging failed webhook deliveries

• Auditing webhook activity

• Checking delivery success rates

RETURNS:

• deliveries: Array of delivery records with:

  • delivery_id: Unique delivery ID

  • event: Event type

  • status: success/failed

  • response_code: HTTP response code

  • response_time_ms: Response time

  • attempted_at: Attempt timestamp

  • error: Error message (if failed)

• total: Total delivery count

• success_rate: Percentage of successful deliveries

EXAMPLE: User: "Show me failed deliveries for this webhook" get_webhook_deliveries({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d", status: "failed", limit: 20 })

List all devices registered to the partner account.

WHEN TO USE:

• Getting an overview of all connected devices

• Finding devices by status (online/offline)

• Auditing the device fleet

RETURNS:

• devices: Array of device objects

• total: Total device count

• online_count: Number of online devices

• offline_count: Number of offline devices

EXAMPLE: User: "Show me all my online devices" list_devices({ status: "online", limit: 50 })

List all webhook subscriptions for the partner account.

WHEN TO USE:

• Viewing all configured webhooks

• Auditing webhook subscriptions

• Finding a webhook to update or delete

RETURNS:

• webhooks: Array of webhook objects with:

  • webhook_id: Unique identifier

  • url: Endpoint URL

  • events: Subscribed events

  • enabled: Whether webhook is active

  • created_at: Creation timestamp

  • last_delivery: Last successful delivery time

EXAMPLE: User: "Show me all my webhooks" list_webhooks({})

[AdCP Media Buy] Record a conversion or attribution event.

Records conversion events for post-campaign attribution analysis. Events are deduplicated by event_id + event_type combination.

WHEN TO USE:

• Recording offline conversions (store visits, purchases)

• Tracking post-view attribution events

• Logging custom KPI events

EXAMPLE: log_event({ media_buy_id: "mbuy_abc123", event: { event_id: "conv_12345", event_type: "store_visit", value_cents: 5000, screen_id: "507f1f77bcf86cd799439011", metadata: { store: "NYC-001", dwell_minutes: 12 } } })

[AdCP Media Buy] Provide optimization signals from buyer agent.

Accepts feedback from buyer agents for floor price adjustment and inventory optimization. Enables closed-loop optimization between buyer and seller agents.

WHEN TO USE:

• Sending bid response feedback to optimize future pricing

• Providing conversion data for bid price calibration

• Adjusting floor prices based on demand signals

EXAMPLE: provide_performance_feedback({ media_buy_id: "mbuy_abc123", feedback: { type: "bid_response", avg_bid_price_cpm: 6.5, fill_rate_percent: 72, preferred_hours: [8, 9, 10, 17, 18], quality_score: 0.85 } })

Purchase committed-use credits at a discount. Three tiers: tier_500 ($500 → $625 credit, 25% bonus), tier_2000 ($2,000 → $3,100 credit, 55% bonus), tier_5000 ($5,000 → $10,000 credit, 100% bonus). Requires an active payment method.

Record a single ad impression from a device.

WHEN TO USE:

• Reporting that an ad was displayed on a device

• Recording impression with detailed metadata

• Single impression events (for batch, use batch_impressions)

RETURNS:

• success: Boolean indicating success

• impression_id: Unique impression identifier

• earnings: Earnings credited for this impression

EXAMPLE: User: "Record an impression for ad 507f1f77bcf86cd799439011" record_impression({ fingerprint: "P_abc123", ad_id: "507f1f77bcf86cd799439011", duration_seconds: 15 })

Register or update a device in the partner's network.

WHEN TO USE:

• Adding a new screen/kiosk/vending machine to the network

• Updating device location or configuration

• Re-registering a device after maintenance

RETURNS:

• device_id: Your internal device ID (echoed back)

• trillboards_device_id: Internal Trillboards device ID

• fingerprint: Device fingerprint (e.g., "P_abc123")

• embed_url: URL to load in the device's WebView

• status: Device status

EXAMPLE: User: "Register a vending machine in NYC" register_device({ device_id: "vending-001-nyc", name: "NYC Office Lobby Vending", device_type: "vending_machine", location: { lat: 40.7128, lng: -74.0060, city: "New York", state: "NY", venue_type: "office" } })

Register a new partner organization with Trillboards.

WHEN TO USE:

• First-time setup for a new partner integration

• Creating a new partner account to manage devices

RETURNS:

• partner_id: Unique partner identifier

• api_key: API key for authenticated requests (store securely!)

• status: Account status

EXAMPLE: User: "Register my vending machine company" register_partner({ company_name: "Acme Vending Co", email: "tech@acmevending.com", industry: "vending", expected_devices: 50 })

Search screens by natural language scene description using pgvector.

Uses 768-dimensional Gemini embeddings on scene descriptions from FEIN edge AI to find screens matching a natural language query.

WHEN TO USE:

• Finding screens by audience context ("families eating lunch in a food court")

• Contextual ad placement based on real-time scene understanding

• Discovering inventory matching a specific audience scenario

RETURNS: Array of matching screens ranked by semantic similarity, each with:

• screen_id, mongo_screen_id, scene_description, contextual_relevance, similarity, created_at

EXAMPLE: semantic_audience_search({ query: "young professionals in a coffee shop looking at phones", limit: 10 })

Set up pay-per-use billing with a Stripe payment method. Required after exceeding free tier limits. Pass a Stripe payment method token (pm_xxx) obtained from Stripe.js or Stripe Elements.

[AdCP Media Buy] Validate and sync creative assets for a media buy.

Validates creative assets (resolution, duration, format) against screen specifications. Returns compatibility status for each screen in the campaign.

WHEN TO USE:

• Submitting creative assets before campaign launch

• Checking if a creative meets screen requirements

• Validating VAST tags

EXAMPLE: sync_creatives({ media_buy_id: "mbuy_abc123", creatives: [{ url: "https://cdn.example.com/ad.mp4", type: "video", width: 1920, height: 1080, duration_seconds: 15, file_size_mb: 12 }] })

Send a test event to a webhook endpoint.

WHEN TO USE:

• Verifying webhook endpoint is working

• Testing integration during development

• Debugging webhook delivery issues

RETURNS:

• success: Boolean indicating delivery success

• response_code: HTTP response code from endpoint

• response_time_ms: Response time in milliseconds

• error: Error message if delivery failed

EXAMPLE: User: "Test my webhook with a device.online event" test_webhook({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d", event: "device.online" })

[AdCP Media Buy] Update an existing media buy (campaign).

Modify budget, targeting, schedule, or status of an existing media buy.

WHEN TO USE:

• Adjusting campaign budget mid-flight

• Pausing or resuming a campaign

• Changing targeting parameters

• Extending campaign dates

EXAMPLE: update_media_buy({ media_buy_id: "mbuy_abc123", updates: { status: "paused", budget: { daily_usd: 300 } } })

Update an existing webhook subscription.

WHEN TO USE:

• Changing the webhook endpoint URL

• Adding or removing subscribed events

• Enabling or disabling a webhook

• Updating the webhook description

RETURNS:

• webhook_id: The updated webhook ID

• url: Updated endpoint URL

• events: Updated event subscriptions

• enabled: Updated enabled status

• updated_at: Update timestamp

EXAMPLE: User: "Disable the webhook for maintenance" update_webhook({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d", enabled: false })

User: "Add impression events to my webhook" update_webhook({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d", events: ["device.online", "device.offline", "impression.recorded"] })

Verify cryptographic proof of ad delivery or get campaign proofs.

Requires either campaign_id or proof_payload (at least one must be provided).

Two modes:

1. Verify a proof: pass proof_payload with signature fields to verify

2. Get proofs: pass campaign_id to get Ed25519-signed proofs for a campaign

Uses Ed25519 signatures (v2) that can be independently verified by third parties using the Trillboards public key.

WHEN TO USE:

• Verifying that ads were actually delivered to screens

• Exporting cryptographically signed proof records for auditors

• Getting proof-of-play data for campaign transparency reports

RETURNS (verify mode):

• valid: boolean, reason: string if invalid, version: 'v1' or 'v2'

RETURNS (get proofs mode):

• campaignId, totalImpressions, proofsReturned

• proofs: Array of signed impression proofs

• pagination: { limit, hasMore, nextCursor }

• signatureVersion, publicKeyUrl

EXAMPLE (verify): verify_proof_of_play({ proof_payload: { signature: "ed25519=abc123...", timestamp: "2026-03-10T15:30:00Z", adId: "ad_123", impressionId: "imp_456", screenId: "scr_789", deviceId: "dev_012" } })

EXAMPLE (get proofs): verify_proof_of_play({ campaign_id: "camp_abc123", start_date: "2026-03-01", end_date: "2026-03-10" })