VISWOO DOCUMENTATION
Introduction to the Viswoo API
Manage screens, content and reports from your own systems; keys, permissions, errors and limits.
The Viswoo API lets a business manage its screens, content and reports from its own systems (ERP, campaign tools, price databases). It is separate from plugins: a plugin is an app that runs on the screen, the API is requests from your server to a Viswoo account.
The API works while the customer has the API access add-on turned on (included in V-Premium, available on the add-ons page for other plans). Reports also need the Reports add-on.
Address
Section titled “Address”https://api.viswoo.com/api/ext/v1Every request is HTTPS. Bodies are JSON with camelCase fields; times are UTC ISO 8601 (2026-11-01T09:30:00Z),
dates yyyy-MM-dd, ids UUIDs. Enum values are text starting with a lowercase letter (landscape, ready).
The account owner or an admin creates a key in the panel under Add-ons → API access. The key starts with vzk_
and is shown only once when created; Viswoo stores only its hash. The key belongs to the business, not a person: it
keeps working when the person who created it leaves the team. It is valid for 90 days, 1 year or without expiry and
can be revoked in the panel at any time.
Send it in the Authorization header with every request:
curl https://api.viswoo.com/api/ext/v1/me \ -H "Authorization: Bearer vzk_..."Never use the key in a browser or a mobile app; keep it on your server only.
Permissions
Section titled “Permissions”Permissions are chosen when the key is created; each endpoint needs one. Give a key only what it needs.
| Permission | What it allows |
|---|---|
screens:read |
Locations, screens, live status, command status, app screenshot |
screens:write |
Screen settings and remote commands (refresh, reboot, screenshot…) |
content:read |
Media, folders, playlists, schedule rules, impact dry run, emergency alerts |
content:write |
Media upload, folder, playlist and schedule changes, emergency alerts |
reports:read |
Proof-of-play and uptime reports (JSON and CSV) |
webhooks:manage |
Webhook addresses and delivery log |
Changes made with a key go live right away as if an admin of the account made them (even with content approval on)
and are written to the audit log as “API:
Errors
Section titled “Errors”Errors use the ProblemDetails format with a machine-readable code:
{ "status": 404, "title": "screen.not_found", "code": "screen.not_found" }| Status | Meaning |
|---|---|
400 |
Invalid request; on validation errors errors lists codes per field |
401 |
api_key.invalid: missing, wrong, expired or revoked key |
402 |
subscription.suspended: account suspended; reads work, writes don’t |
403 |
api_key.scope_missing (no permission) or feature.not_subscribed (add-on off) |
404 |
Not found, or belongs to another business (existence is not revealed) |
409 |
Conflict: e.g. media.in_use, folder.name_taken, screen.no_device |
429 |
request.rate_limited: rate limit exceeded |
Paging
Section titled “Paging”Lists take page (starting at 1) and pageSize (at most 100, default 50):
{ "items": [], "page": 1, "pageSize": 50, "total": 132 }The order is stable; increase page to get the next page.
Limits
Section titled “Limits”120 requests per minute per key. Above that you get 429; wait a few seconds and retry. Media files don’t go
through the API: they are uploaded straight to a time-limited address (quickstart).
Versioning
Section titled “Versioning”The path is v1 and only grows (new fields, new endpoints); ignore fields you don’t know. A breaking change comes
as v2, and v1 keeps working alongside it for at least 6 months. Changes are announced in the
changelog.
Every endpoint and schema is in the API reference; event notifications are on the webhooks page.