API reference

Every endpoint in the /v1 contract. 23 of the 65 are available during early access, and the others are marked. New to the API? Start with the quickstart.

Base URLs

Environment	Base URL
Production	`https://api.vojo-media.com`
Development	`https://dev.api.vojo-media.com`

Account

The signed-in user, organisations and entitlements.

Screens

Physical displays and their links to sites and devices.

Sites

Physical locations that contain screens.

Harvesters

Vojo's optical sensors, fitted to screens.

Clients

Advertisers the organisation works for (read-only).

Campaigns

Campaigns (read-only in v1).

Creatives: upload, register, update, archive.

Wrappers

Wrap a creative in a Vojo Passport.

Plays

Plays, with their score, band and phase, and the evidence events matched into each one.

Webhooks

Register the endpoints Vojo delivers events to, roll their signing secrets and inspect deliveries. See Receive webhooks and the event reference.

Stats

Aggregate reads. Every play count is a count of plays, the same unit GET /v1/plays lists, so totals reconcile with the play list.

Dashboards

Saved dashboards (user-owned; OAuth only).

Scopes

A secret key or OAuth token only reaches the endpoints its scopes allow. A missing scope returns insufficient_scope.

Scope	Allows
`account:read`	Read the signed-in user, accessible organisations and entitlements.
`account:write`	Create organisations and set the default organisation.
`screens:read`	Read screens and screen size ranges.
`screens:write`	Create, update and delete screens; assign sites and harvesters; calibrate.
`sites:read`	Read sites.
`sites:write`	Create, update and delete sites.
`harvesters:read`	Read harvesters.
`harvesters:write`	Activate harvesters.
`campaigns:read`	Read campaigns.
`advertisements:read`	Read advertisements.
`advertisements:write`	Upload, register, update and archive advertisements.
`clients:read`	Read clients.
`stats:read`	Read aggregate statistics and issues.
`plays:read`	Read plays and their evidence events.
`webhooks:read`	Read webhook endpoints and their deliveries.
`webhooks:write`	Create, change, delete webhook endpoints, roll their secrets and retry deliveries.
`wrappers:write`	Wrap creatives in a Vojo Passport.
`dashboards:read`	Read saved dashboards.
`dashboards:write`	Create, update and delete the user's dashboards.