Docs API reference

Getting started

From a new workspace to a screen that plays: the setup checklist, and quick starts that make a news feed story, a TV channel story, or headlines followed by a few minutes of TV — ordinary stories and scenes you can change afterwards.

Read the setup checklist

GET /setup stages

What the workspace still needs before a screen plays, in order: a venue, a stage, a connected screen, a story, something on the screen; TV channels are optional.

Responses

200 The checklist.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.

Response fields (200)

done boolean required

A screen is connected and has something to play.
facts object

The counts the steps read.
steps object[] required
6 fields in steps
- step string
  
  One of venue, stage, screen, story, play, channels
- title string
- done boolean
- optional boolean
- blocked string or null
  
  The step before it is missing.
- what string

Request

curl "https://www.wunderframe.com/api/v1/setup" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY"

Response 200

{
  "done": false,
  "facts": {
    "venues": 1,
    "stages": 1,
    "screens": 0,
    "stories": 0,
    "onScreen": 0,
    "channels": 0
  },
  "steps": [
    {
      "step": "venue",
      "title": "Add a venue",
      "done": true,
      "optional": false,
      "blocked": null,
      "what": "The place your screens are in…"
    },
    {
      "step": "screen",
      "title": "Connect the screen",
      "done": false,
      "optional": false,
      "blocked": null,
      "what": "Open the Wunderframe app on the TV…"
    }
  ]
}

Error example

Response 401

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key."
  }
}

News from a feed

POST /quick-starts/news authoring

A collection fed by the feed (read now, then every 15 minutes), a Headline template and a story that rolls through the newest items, per_pass (default 5) each round. Needs authoring and data.

Request body required

url string required

RSS, Atom, JSON Feed — or a news website.
name string
per_pass integer

1–20
stage_id string

Optional: put the story on this stage (its story whenever nothing is booked). Needs the stages scope too.

Responses

201 What was made.
400 The request is invalid — details.field names the field when there is one.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.

Response fields (201)

storyId string required

The story made — GET /stories/{id}.
scenes object[] required

The designs made, to edit (the headline template, the TV scene).
2 fields in scenes
- id string
- label string
collectionId string

The feed’s collection, when there is one.
items integer

Feed items read so far.
syncError string or null

Why the feed could not be read yet.
normalStoryId string

Someone in front: the story the stage plays the rest of the time.
stageId string

Someone in front: the stage set up — try it in its preview.

Request

curl -X POST "https://www.wunderframe.com/api/v1/quick-starts/news" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://www.srf.ch/news/bnf/rss/1646",
  "name": "News",
  "per_pass": 5
}'

Response 201

{
  "storyId": "sto_1",
  "scenes": [
    {
      "id": "scn_1",
      "label": "the headline design"
    }
  ],
  "collectionId": "col_news",
  "items": 40,
  "syncError": null
}

Error example

Response 400

{
  "error": {
    "code": "invalid",
    "message": "The request is invalid — `details.field` names the field when there is one."
  }
}

A TV channel

POST /quick-starts/tv authoring

A scene with the channel full screen, its name and a clock, alone in a story — it plays and stays, never restarting.

Request body required

channel_id string required

A channel id (GET /channels), or "stage" for the stage’s channel (PUT /stages/{id}/channel switches it).
default_channel_id string

With "stage": shown until the stage’s channel is set.
title string
stage_id string

Optional: put the story on this stage (its story whenever nothing is booked). Needs the stages scope too.

Responses

201 What was made.
400 The request is invalid — details.field names the field when there is one.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.

Response fields (201)

storyId string required

The story made — GET /stories/{id}.
scenes object[] required

The designs made, to edit (the headline template, the TV scene).
2 fields in scenes
- id string
- label string
collectionId string

The feed’s collection, when there is one.
items integer

Feed items read so far.
syncError string or null

Why the feed could not be read yet.
normalStoryId string

Someone in front: the story the stage plays the rest of the time.
stageId string

Someone in front: the stage set up — try it in its preview.

Request

curl -X POST "https://www.wunderframe.com/api/v1/quick-starts/tv" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channel_id": "stage",
  "default_channel_id": "ch_srf1",
  "title": "TV"
}'

Response 201

{
  "storyId": "sto_1",
  "scenes": [
    {
      "id": "scn_1",
      "label": "the headline design"
    }
  ],
  "collectionId": "col_news",
  "items": 40,
  "syncError": null
}

Error example

Response 400

{
  "error": {
    "code": "invalid",
    "message": "The request is invalid — `details.field` names the field when there is one."
  }
}

News, then TV

POST /quick-starts/news-then-tv authoring

The news feed and Headline template, the TV scene, and a story: per_pass headlines, then the channel for tv_minutes (default 2), round and round. Change the TV time later with PATCH /chapters/{id} play_for_ms. Needs authoring and data.

Request body required

url string required
channel_id string required

A channel id (GET /channels), or "stage" for the stage’s channel (PUT /stages/{id}/channel switches it).
default_channel_id string
name string
tv_minutes number

At least 0.5
per_pass integer

1–20
stage_id string

Optional: put the story on this stage (its story whenever nothing is booked). Needs the stages scope too.

Responses

201 What was made.
400 The request is invalid — details.field names the field when there is one.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.

Response fields (201)

storyId string required

The story made — GET /stories/{id}.
scenes object[] required

The designs made, to edit (the headline template, the TV scene).
2 fields in scenes
- id string
- label string
collectionId string

The feed’s collection, when there is one.
items integer

Feed items read so far.
syncError string or null

Why the feed could not be read yet.
normalStoryId string

Someone in front: the story the stage plays the rest of the time.
stageId string

Someone in front: the stage set up — try it in its preview.

Request

curl -X POST "https://www.wunderframe.com/api/v1/quick-starts/news-then-tv" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://www.srf.ch/news/bnf/rss/1646",
  "channel_id": "ch_srf1",
  "tv_minutes": 2,
  "per_pass": 5
}'

Response 201

{
  "storyId": "sto_1",
  "scenes": [
    {
      "id": "scn_1",
      "label": "the headline design"
    }
  ],
  "collectionId": "col_news",
  "items": 40,
  "syncError": null
}

Error example

Response 400

{
  "error": {
    "code": "invalid",
    "message": "The request is invalid — `details.field` names the field when there is one."
  }
}

Someone in front of the screen

POST /quick-starts/attract authoring

The stage plays normal all day and attract while someone stands close to it: its camera is turned on (MediaPipe face detection on the screen; nothing is recorded), normal becomes its all-day story and the rule goes first in its list. A lobby: news, then a welcome while someone is there; a TV: a channel, then the news. distance: close ≈ 1 m (default), near ≈ 2 m, room ≈ 4 m; leave_s: keep playing after they leave (default 10). Needs authoring, data and stages.

Request body required

stage_id string required

A single screen (not a wall).
normal object required

{ kind: "news", url, name? } · { kind: "tv", channel_id, default_channel_id? } · { kind: "story", story_id } · { kind: "welcome", headline, line? }.
8 fields in normal
- kind string required
  
  One of news, tv, story, welcome
- url string
- name string
- channel_id string
  
  A channel id (GET /channels), or "stage" for the stage’s channel (PUT /stages/{id}/channel switches it).
- default_channel_id string
- story_id string
- headline string
- line string
attract object required

{ kind: "news", url, name? } · { kind: "tv", channel_id, default_channel_id? } · { kind: "story", story_id } · { kind: "welcome", headline, line? }.
8 fields in attract
- kind string required
  
  One of news, tv, story, welcome
- url string
- name string
- channel_id string
  
  A channel id (GET /channels), or "stage" for the stage’s channel (PUT /stages/{id}/channel switches it).
- default_channel_id string
- story_id string
- headline string
- line string
distance string

One of close, near, room
leave_s number

1–600

Responses

201 What was made.
400 The request is invalid — details.field names the field when there is one.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.
404 Not found in this workspace.

Response fields (201)

storyId string required

The story made — GET /stories/{id}.
scenes object[] required

The designs made, to edit (the headline template, the TV scene).
2 fields in scenes
- id string
- label string
collectionId string

The feed’s collection, when there is one.
items integer

Feed items read so far.
syncError string or null

Why the feed could not be read yet.
normalStoryId string

Someone in front: the story the stage plays the rest of the time.
stageId string

Someone in front: the stage set up — try it in its preview.

Request

curl -X POST "https://www.wunderframe.com/api/v1/quick-starts/attract" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "stage_id": "stg_lobby",
  "normal": {
    "kind": "news",
    "url": "https://www.srf.ch/news/bnf/rss/1646"
  },
  "attract": {
    "kind": "welcome",
    "headline": "Welcome",
    "line": "Reception is on your left"
  },
  "distance": "close"
}'

Response 201

{
  "storyId": "sto_1",
  "scenes": [
    {
      "id": "scn_1",
      "label": "the headline design"
    }
  ],
  "collectionId": "col_news",
  "items": 40,
  "syncError": null
}

Error example

Response 400

{
  "error": {
    "code": "invalid",
    "message": "The request is invalid — `details.field` names the field when there is one."
  }
}