VisionDigit Docs
Edit on GitHub

API Reference

VisionDigit has a JSON REST API under a versioned base URL. The CMS itself is built on it. A dedicated Integration API for connecting other systems, with its own credentials, permission scopes and organization binding, is being built; this page says plainly what works today and what is coming.

Base URL

https://api.visiondigit.com/api/v1

The version is part of the URL. Changes within v1 only add things; anything breaking will come as v2.

Authentication today

Requests are made as a signed-in person: sign in with POST /auth/login, then send the returned token and the organization you are working in:

Authorization: Bearer <token>
X-Org-Id: <organization id>

The token carries that person's role, so use a dedicated account with the least role needed. API keys created in Settings › API Keys are currently accepted only for audience data ingestion; they will unlock the rest of the API with the Integration API.

Coming with the Integration API

  • Per-integration client credentials (OAuth 2.0 client credentials), never shared keys.
  • Granular scopes such as screens.read, media.write, playlists.write.
  • Each client bound to the organizations it may use, enforced by the server.
  • Idempotency-Key support and external references on created content.
  • Creating and publishing designs from templates without handling canvas data.

Main resources

  • GET /screens, POST /screens/:id/assign — screens, their status, and putting a playlist on a screen.
  • POST /screens/:id/commands/reboot (also clear-cache, screenshot, reload-playlist) — remote actions.
  • GET /assets, POST /assets — media library and uploads.
  • GET /playlists, POST /playlists/:id/items — playlists and their content.
  • GET /schedules — schedules.
  • GET /analytics/proof-of-play — proof-of-play records, with a CSV export.

Webhooks

Instead of polling, subscribe to events such as screen.offline, screen.online and playlist.assigned in Settings › Webhooks. Each delivery is signed: the X-VisionDigit-Signature header is sha256= plus the HMAC-SHA256 of the raw body keyed with your webhook secret. Failed deliveries are retried for an hour and can be resent from the delivery history.

Rate limits

Per signed-in person, by plan: Starter 300, Pro 1,000 and Enterprise 5,000 requests per minute. Responses include X-RateLimit-Limit and X-RateLimit-Remaining; going over returns 429 Too Many Requests.

Errors

Errors return an HTTP status with a JSON body. Access problems use {"error": {"code": "…", "message": "…"}} (for example ORG_ACCESS_DENIED, ROLE_REQUIRED); validation errors return 422 with the problem for each field.