Digital Signage API

Base URL

https://infoslides.app

Every path below is relative to this host. The machine-readable description of the same surface lives at /v1/openapi.json and needs no credential to fetch.

Authentication

Send a workspace API key as a bearer token on every request:

Authorization: Bearer isk_admin_…

A tenant session token obtained through the CLI login flow (infoslides login) works anywhere an admin key does.

POST /v1/tenants is the one anonymous endpoint. It provisions a brand-new workspace on the permanent free plan (1 screen, 4 slideshows, 2 users, 200 MB, no credit card, no expiry) and returns its admin API key exactly once — the key is never recoverable afterwards. Nothing else under /v1 is reachable without a credential.

Response envelopes

Every JSON response wraps its payload in data, with optional warnings:

{
  "data": { "deviceId": "…", "name": "Lobby screen" },
  "warnings": [ { "code": "AspectMismatch", "message": "…" } ]
}

Errors use a parallel shape, with details.fields populated on validation failures:

{
  "error": {
    "code": "ValidationFailed",
    "message": "Unknown signup source 'banana'.",
    "details": { "fields": { "source": ["Must be one of: Unknown, Web, Api, Cli, Mcp."] } }
  }
}

Two responses are deliberately not enveloped: GET /v1/slides/{id}/preview.png returns raw image/png bytes, and the CLI auth legs return HTTP redirects.

Idempotency

Creating endpoints accept an Idempotency-Key request header (up to 128 characters). The first successful response for a key is stored for 24 hours; a repeat request with the same key returns that stored response verbatim, with Idempotent-Replay: true, without re-executing the action. This matters for agents, which retry more readily than humans do.

Endpoints that honour it are marked idempotent in the tables below.

Endpoints

Error codes

Every error envelope carries exactly one of these codes, so a client can branch on error.code rather than parsing messages.

Zero to a live screen

Four calls take a brand-new workspace to a playable HLS stream. The first is anonymous; the rest use the key it returns.

# 1. Provision a workspace (anonymous) — returns an admin API key, once.
curl -X POST https://infoslides.app/v1/tenants \
  -H 'Content-Type: application/json' \
  -d '{"tenantName":"Acme Cafe","ownerEmail":"[email protected]","source":"api"}'

# 2. Clone a starter deck from the gallery.
curl -X POST https://infoslides.app/v1/gallery/$GALLERY_ID/clone \
  -H "Authorization: Bearer $ISK"

# 3. Register the screen.
curl -X POST https://infoslides.app/v1/devices \
  -H "Authorization: Bearer $ISK" -H 'Content-Type: application/json' \
  -d '{"name":"Lobby screen"}'

# 4. Assign the deck, then read the stream link.
curl -X POST https://infoslides.app/v1/devices/$DEVICE_ID/schedule \
  -H "Authorization: Bearer $ISK" -H 'Content-Type: application/json' \
  -d '{"slideshowId":"'$SLIDESHOW_ID'"}'
curl https://infoslides.app/v1/devices/$DEVICE_ID/stream \
  -H "Authorization: Bearer $ISK"

The same workflow is available as a CLI and as an MCP server for AI agents — one dependency-free binary, 27 tools. See github.com/arnibj/InfoSlides.MCP or the agent guide.