1.0 | Introduction
The BBSapi PowerShell module is an official Blue Billywig module for the Server API (SAPI). It runs on PowerShell 7+ on Windows, macOS, and Linux, and follows standard PowerShell conventions including approved verbs and -WhatIf support. It covers entity CRUD operations, TUS-based file uploads to S3, analytics helpers, and version history for any entity.
GitHub repository: bluebillywig/bb-sapi-powershell
2.0 | Requirements
- PowerShell 7 or higher (Windows, macOS, or Linux)
3.0 | Installation
Install-Module -Name BBSapi -Scope CurrentUserTo install from source:
git clone https://github.com/bluebillywig/bb-sapi-powershell.git
Import-Module ./bb-sapi-powershell/BBSapi/BBSapi.psd14.0 | Authentication
The module uses HOTP-based RPC token authentication. You need the shared secret from your Blue Billywig publication (see API key management).
The shared secret shown in your account settings has the format {id}-{hex_secret}, for example 490-55c491d354cfefb9b4d26cf22fbdd0a1. Pass this full value to Connect-BBSapi.
Connect-BBSapi -BaseUrl 'https://mypub.bbvms.com' -SharedSecret '490-55c491d354cfefb9b4d26cf22fbdd0a1'Never embed credentials directly in scripts. Store them using PowerShell SecretManagement instead:
Install-Module Microsoft.PowerShell.SecretManagement
Set-Secret -Name BBSapiSecret -Secret '490-55c...'
Connect-BBSapi -BaseUrl 'https://mypub.bbvms.com' -SharedSecret (Get-Secret -Name BBSapiSecret -AsPlainText)
The token is time-based with a 120-second validity window. Ensure your server clock is synchronized with NTP.
5.0 | Quick start
5.1 | Entity operations
# Get a mediaclip
Get-BBSapiEntity -Entity mediaclip -Id 12345
# List published clips
Get-BBSapiEntityList -Entity mediaclip -Limit 20 -Sort 'createddate DESC' `
-Filters @{ status = 'published' }
# Search (Solr query syntax)
Search-BBSapi -Query 'title:football' -EntityType MediaClip -Limit 10
# Create
New-BBSapiEntity -Entity mediaclip -Data @{ title = 'My Video'; status = 'draft' }
# Update
Set-BBSapiEntity -Entity mediaclip -Id 12345 -Data @{ title = 'Updated Title' }
# Delete (soft)
Remove-BBSapiEntity -Entity mediaclip -Id 12345
# Delete permanently (supports -WhatIf)
Remove-BBSapiEntity -Entity mediaclip -Id 12345 -Purge5.2 | Upload a video and create a mediaclip
$result = New-BBSapiMediaClip `
-FilePath 'C:\videos\match.mp4' `
-Title 'Match Recap' `
-Status draft `
-OnProgress { param($done, $total)
Write-Progress -Activity 'Uploading' -PercentComplete ($done / $total * 100) }
$result.MediaclipIdTo upload a file without creating a new mediaclip entity (for example, to attach a subtitle or replace a creative), use Send-BBSapiFile instead:
Send-BBSapiFile -FilePath 'C:\subs\en.srt' -MediaclipId 123455.3 | Analytics
The BBSapi module includes convenience helpers for common analytics queries.
# Top 10 videos for a date range
Get-BBSapiTopVideos -FromDate '2026-01-01' -ToDate '2026-03-31' -Limit 10
# Unique viewers for a specific video
Get-BBSapiUniqueViewers -EntityType mediaclip -EntityId 12345 `
-FromDate '2026-01-01' -ToDate '2026-03-31'
# Time-series views, day by day
Get-BBSapiAnalyticsRange -EntityType mediaclip `
-FromDate '2026-01-01' -ToDate '2026-03-31' -Granularity day
# Ad impressions and VAST quartiles per video
$ad = Get-BBSapiAdStats -EntityId 12345 -FromDate '2026-01-01' -ToDate '2026-03-31'
$ad.Impressions # total ad impressions (lineitemInits)
$ad.VastQuartiles['50'] # sessions where the ad reached 50%5.4 | Version history
The module can retrieve version history for any entity, which is useful for auditing changes or identifying which creative was active during a report period.
Get-BBSapiVersions -Entity mediaclip -Id 12345
Get-BBSapiVersions -Entity lineitem -Id starcasino_preroll6.0 | Full documentation
The GitHub README contains the complete command reference, analytics API details, TUS upload flow, and additional examples including a ready-to-run analytics export script: github.com/bluebillywig/bb-sapi-powershell