Trillboards DOOH Advertising

[AdCP Accounts] List the accounts this credential can transact on. This seller's account model is 'explicit': one API key IS one account, so this returns exactly one account — the partner behind the key. Use it to discover your account_id before any account-scoped call, and to confirm the account's status before you buy. WHEN TO USE: - Discovering the account_id to pass to account-scoped tasks - Checking your account is 'active' before creating a media buy - Introspecting what your key is permitted to do (accounts[].authorization.allowed_tasks) RETURNS: - accounts: AdCP Account objects (account_id, name, status, operator, brand, billing, account_scope) plus an authorization object naming the tasks this key may invoke - pagination: has_more is always false — one credential, one account EXAMPLE: list_accounts({}) list_accounts({ status: "active" })

[AdCP Media Buy] List the creative formats this network actually accepts. Every format is DERIVED from live per-screen capability (panel size, min/max spot length, audio) — not a hand-written list. The set published here is exactly the set sync_creatives accepts: if a creative matches a format returned by this tool, it will not be rejected for dimensions, duration or file size. WHEN TO USE: - Before building creative, to size it to the panels you are buying - To check whether an existing asset can run on this network - To find the panel sizes with the most reach (results are ordered by live screen count) RETURNS: - formats: AdCP Format objects (format_id, name, renders[].dimensions, assets[].requirements) - pagination: cursor-based; total_count is the full catalogue size - Each format carries ext.trillboards with the live screen count, the share of the network, how many of those screens have audio, and — for video — duration_coverage: how many screens accept a spot of at most 10/15/20/30/60/120/300 seconds. A long ceiling does not mean every screen at that size can play it, and this says so. EXAMPLE: User: "What sizes and lengths does this network take?" list_creative_formats({ pagination: { max_results: 20 } }) User: "Can I run a 1080x1920 portrait video?" list_creative_formats({ format_ids: [{ agent_url: "https://api.trillboards.com/mcp", id: "dooh_video_1080x1920" }] })

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 every registered Trillboards API operation. WHEN TO USE: - First call in an agent session to learn what the API offers. - Filter to agent_safe=true to list only side-effect-free endpoints. - Narrow to a single surface (data-api, sdk-api, device-api, sensing-api, partner-api-generated, dsp-api-generated). RETURNS: - operations: Array of { surface, method, path, operation_id, summary, description, agent_safe, idempotent, cost_tier, tags, doc_url, example_request } - total_operations: Total count. - surfaces: Known surface identifiers. EXAMPLE: Agent: "What read-only endpoints can I call?" list_endpoints({ agent_safe: true })

List every error code in the Trillboards API error catalog. WHEN TO USE: - Understanding what error codes the API can return. - Building a client-side error handler that covers all cases. - Looking up error types, HTTP statuses, and documentation URLs. RETURNS: - object: "list" - data: Array of { code, type, http_status, description, doc_url } - total: Total number of error codes. Equivalent to GET /v1/errors but executed in-process (no HTTP round-trip). EXAMPLE: Agent: "What error codes can the API return?" list_error_codes()

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 } } })

Predict the VAS (Viewability Attention Score) a specific creative would achieve at a given moment, based on historical data and causal modeling. Uses the CausalPredictionService which: 1. Embeds the moment description to find historically similar moments 2. If >= 5 similar moments exist with the same creative, uses weighted-average prediction 3. If insufficient data, falls back to Gemini generative prediction 4. Always decomposes the prediction into causal factors WHEN TO USE: - Evaluating whether a creative will perform well in a specific context - A/B testing creative placement hypotheses before committing budget - Understanding which causal factors drive VAS for a creative - Comparing expected performance across different moment types RETURNS: - prediction: { predictedVAS (0-1), confidence (0-1), method ('historical'|'model'), sampleSize } - causal_factors: { audienceMatch, contextMatch, attentionState, socialPotential } (each 0-1) - metadata: { creative_id, moment_description } - suggested_next_queries: Follow-up queries EXAMPLE: User: "How would a coffee ad perform at a transit station during morning rush?" predict_moment_quality({ moment_description: "transit venue, morning commute, 12 viewers, high attention, mostly 25-34 age range", creative_id: "coffee-brand-morning-30s" })

Generate predictive insights from observation patterns. Predict whether a venue is likely to see increased foot traffic based on current patterns. Uses historical observation_stream data to compute trend analysis via linear regression on time-bucketed metrics. Generates predictions with confidence intervals based on the observed trend, variance, and sample size. WHEN TO USE: - Predicting future audience patterns at a venue or screen - Forecasting foot traffic trends for campaign planning - Understanding whether metrics are trending up, down, or stable - Making data-driven decisions about inventory and pricing RETURNS: - prediction: The predicted trend and expected values - trend: 'increasing' | 'decreasing' | 'stable' - current_avg: Current average metric value - predicted_avg: Predicted average over the time horizon - change_pct: Expected percentage change - confidence_interval: { lower, upper } bounds - confidence: Overall prediction confidence (0-1) - supporting_data: Recent data points that inform the prediction - data_points: Array of { bucket, avg_value, sample_count } - total_observations: Total observations analyzed - methodology: Description of the prediction approach - suggested_next_queries: Follow-up queries to refine the prediction EXAMPLE: User: "Will this QSR venue see more foot traffic next week?" predictive_query({ question: "Will foot traffic increase at QSR venues?", venue_type: "restaurant_qsr", time_horizon: "7d" }) User: "Predict audience attention trends for this screen" predictive_query({ question: "What will audience attention look like?", screen_id: "507f1f77bcf86cd799439011", time_horizon: "3d" })

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

Query the Trillboards API changelog for recent changes, breaking changes, deprecations, and fixes. WHEN TO USE: - Check what has changed in the API before upgrading an integration. - Find breaking changes since a specific date. - Discover new features added to a specific API surface. PARAMETERS: - since (YYYY-MM-DD, optional): Only entries dated on or after this date. Unreleased entries are always included. - type (string, optional): Filter by change category. Accepts: "breaking" → changed + removed entries "additive" → added entries "deprecation" → deprecated entries "fix" → fixed entries Can be comma-separated: "breaking,deprecation" RETURNS: - object: "list" - data: Array of { version, date, type, surface, description } - total: Number of matching entries. EXAMPLE: Agent: "What broke since April 1st?" query_changelog({ since: "2026-04-01", type: "breaking" })

Query the universal observation stream using natural language or structured filters. Returns multi-modal sensing data (audience, vehicle, environment, commerce) from physical-world observations across the screen network. WHEN TO USE: - Exploring raw observation data from edge AI sensors on screens - Filtering observations by venue type, device, time range, or geography - Getting audience, vehicle, environment, or commerce observation data - Answering natural language questions about what screens are sensing RETURNS: - data: Array of observation objects with device, venue, payload, confidence, model versions - metadata: { observation_count, time_range, coverage_pct, model_versions } - suggested_next_queries: Contextual follow-up queries Each observation includes: - observation_id, device_id, screen_mongo_id, venue_type - observed_at: Timestamp of the observation - observation_family: audience | vehicle | environment | commerce - payload: JSONB with model outputs (face_count, emotion, vehicle_count, etc.) - confidence: Model confidence score (0-1) - evidence_grade: Quality grade of the observation - model_versions: Which ML models produced this data EXAMPLE: User: "Show me audience observations at QSR venues in the last hour" query_observations({ query: "audience observations at QSR venues", filters: { observation_family: ["audience"], venue_type: ["restaurant_qsr"], time_range: { start: "2026-03-16T14:00:00Z", end: "2026-03-16T15:00:00Z" } }, limit: 50 }) User: "What are screens sensing right now?" query_observations({ query: "latest observations from all screens", limit: 20 })

Given a moment description, rank candidate creatives by predicted VAS performance. Evaluates each creative candidate against the described moment context using historical similarity and causal prediction. Returns a ranked list sorted by predicted VAS score, with confidence levels for each prediction. WHEN TO USE: - Choosing which creative to show at a specific moment/venue - Comparing multiple creatives for a campaign across different contexts - Optimizing creative rotation for maximum VAS - Pre-campaign creative selection based on audience and venue RETURNS: - rankings: Array sorted by predicted VAS (descending) - creativeId, predictedVAS (0-1), confidence (0-1), rank (1-N) - metadata: { candidate_count, moment_description } - suggested_next_queries: Follow-up queries EXAMPLE: User: "Which of these 3 creatives will perform best at a gym in the evening?" recommend_creative({ moment_description: "gym venue, evening, 6 viewers, high attention, mostly male 18-34", creative_ids: ["fitness-brand-30s", "energy-drink-15s", "tech-gadget-20s"] })

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: "[email protected]", industry: "vending", expected_devices: 50 })

Semantic search over content library using natural language queries and 768-D pgvector embeddings. WHEN TO USE: - Finding content by description or theme ("upbeat music videos", "cooking shows") - Discovering content similar to a concept or mood - Searching the content library without knowing exact titles or IDs - Content discovery for programmatic content scheduling RETURNS: - data: Array of matching content with similarity scores - videoId, title, contentCategory, description, durationSeconds - reviewStatus (approved/pending/rejected) - similarity (0-1, cosine similarity against query embedding) - meta: { count, query, limit, minSimilarity } EXAMPLE: User: "Find fitness and workout content" search_content({ query: "fitness workout exercise gym", limit: 10, min_similarity: 0.6 }) User: "Search for calming nature content suitable for medical offices" search_content({ query: "calming nature scenes peaceful landscapes meditation", min_similarity: 0.5 })

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 })

Search observations by semantic similarity. Find moments that match a description like "lunch rush at fast casual restaurants" using vector embeddings. Uses 768-dimensional Gemini embeddings on observation payloads to find promoted observations matching a natural language query via pgvector cosine similarity search. TIME BOUND: searches the last 30 days by default. Pass filters.time_range to widen or narrow it; the window actually applied is echoed in metadata.time_range. Observations are retained for 90 days. WHEN TO USE: - Finding observations that match a conceptual description - Discovering contextual moments across the screen network - Searching for audience situations ("families waiting in line", "professionals on coffee break") - Finding commerce patterns ("high purchase intent near checkout") RETURNS: - data: Array of matching observations ranked by semantic similarity, each with: - observation_id, device_id, venue_type, observation_family - observed_at, payload, confidence, evidence_grade - similarity: Cosine similarity score (0-1, higher = more relevant) - metadata: { result_count, query_embedding_model, search_scope, time_range } - suggested_next_queries: Related semantic queries to explore EXAMPLE: User: "Find lunch rush moments at fast casual restaurants" semantic_search_observations({ query: "lunch rush at fast casual restaurants with high foot traffic", filters: { venue_type: ["restaurant_qsr"] }, limit: 20 }) User: "Find moments with high emotional engagement" semantic_search_observations({ query: "audience showing strong positive emotional reactions", filters: { observation_family: ["audience"] }, 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 Accounts] Establish or confirm the account behind this credential. IMPORTANT — what this does NOT do: it does not provision a new account. This seller's namespace is one account per API key, so a provisioning-mode entry (brand + operator + billing) is LINKED to the account your key already owns and the response says so in warnings[]. Two different brands on one key resolve to the SAME account_id. Register one agent per brand at https://api.trillboards.com/v1/partner/agent/register if you need per-brand separation. BILLING IS THE ONE SETTING THAT IS APPLIED. Send billing: 'operator' (we invoice you, buying direct) or 'agent' (you are a buying agent consolidating across the brands you front, and we invoice you for all of them — the marketplace-clearing model). The value is stored on the account, reported back by list_accounts, and reflected in action 'updated'. The set we accept is exactly account.supported_billing from get_adcp_capabilities; 'advertiser' is refused, with the reason, because we hold no billing relationship with a third-party advertiser. One key is one account with one invoiced party, so a request declaring two different billing values applies neither and says so. Everything else is read-only and reports 'unchanged': payment terms, billing entity and notification subscriptions are not per-account state on this platform, and anything sent that was not applied is named in warnings[] rather than silently swallowed. WHEN TO USE: - The account-setup step at the start of a buying flow - Declaring how you want to be invoiced, before create_media_buy - Confirming your account_id and status before create_media_buy RETURNS: - accounts: per-entry result with account_id, action ('updated' | 'unchanged' | 'failed'), status, billing, account_scope, and warnings naming anything not applied EXAMPLE: sync_accounts({ idempotency_key: "8f1c...", accounts: [{ brand: { domain: "acme.example" }, operator: "agency.example", billing: "agent" }] })

[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"] })

Validate a proposed request payload against the registered Zod schema for an operation, returning the exact canonical error envelope the HTTP surface would emit. WHEN TO USE: - Before calling a write endpoint, to catch payload bugs locally. - Debugging 400 validation_error responses. RETURNS: - valid: true when the payload would pass Zod validation. - When invalid, the canonical { error: { type, code, message, param, doc_url, details[] } } envelope is included under `error`. EXAMPLE: validate_request({ path: "/v1/data/query", method: "POST", payload: { dataset: "inference_outcomes", limit: 9999 } })

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" })