For scripts and agents
The DreamWidget API
Everything the dashboard does, as plain HTTPS with JSON: make a widget, set its design, add logos or video sources, publish it to the CDN, read its counts. A key opens exactly the doors your account has, under your plan's limits, and nothing else.
A key
On your account page, under API, give the key a name and click Make a key. It is shown once; copy it then. Send it on every call:
Authorization: Bearer dw_live_…
Revoke a key on the same page and anything using it stops at once. An account holds up to five keys. Views of a widget are never metered on a paid plan (a free widget can be shown 300 times a month); the API itself, which builds and edits widgets, allows 600 calls a minute per key, ten a second, a ceiling only a runaway loop reaches. A call over it is answered 429 for the rest of that minute and nothing is lost.
The calls
Base address: https://us-central1-dream-widget.cloudfunctions.net/api/v1. Bodies and answers are JSON.
| Call | What it does |
|---|---|
GET /me | Your plan, its limits, and how many widgets you have. |
GET /widgets | Your widgets, each with its embed code. |
POST /widgets | {"type":"logo"|"video"|"popup"|"showreel"|"countdown"|"instagram","name":"…","settings":{…}}. Starts from the standard design; any settings you pass are laid over it. A one-platform video widget is "yt", "vimeo", "tiktok" or "twitch". A popup floats over the page, so take its embed code from the dashboard, which carries its script. An Instagram feed stays empty until its account is connected in the editor (Connect Instagram), since Instagram has to be signed in to by its owner. |
GET /widgets/:id | The whole widget: settings, logos or tabs. |
PATCH /widgets/:id | {"name","settings","logos","groups","source"}, any of them. Settings merge; lists replace. |
POST /widgets/:id/logos | {"url":"https://…/mark.svg","name":"Acme","link":"https://acme.com"}. The file is fetched, stored on our CDN and added to the list. |
POST /widgets/:id/sources | {"provider":"youtube"|"vimeo"|"twitch"|"tiktok","ref":"…","tab":"Latest"}. Fetches the videos into a tab, making the tab if needed. What to pass as ref is in the sources guide. |
POST /widgets/:id/publish | Puts the widget as it is now on the CDN. Every page embedding it updates within a minute. |
GET /widgets/:id/stats?days=30 | Views, clicks and plays, by day and by item. |
DELETE /widgets/:id | Takes it off the CDN and deletes it. |
A Logo Showcase, start to finish
API=https://us-central1-dream-widget.cloudfunctions.net/api/v1
H="Authorization: Bearer dw_live_…"
# make it
curl -s -X POST $API/widgets -H "$H" -H "Content-Type: application/json" \
-d '{"type":"logo","name":"Partners","settings":{"layout":"ticker","speed":40}}'
# → {"widget":{"id":"abc123","embed":"<iframe …>",…}}
# add logos from anywhere on the web
curl -s -X POST $API/widgets/abc123/logos -H "$H" -H "Content-Type: application/json" \
-d '{"url":"https://acme.com/logo.svg","name":"Acme","link":"https://acme.com"}'
# publish
curl -s -X POST $API/widgets/abc123/publish -H "$H"
# a month later
curl -s "$API/widgets/abc123/stats?days=30" -H "$H"
The settings are the same fields the editor writes. The easiest way to learn them is to set a widget up in the editor, then GET /widgets/:id and read what came back.
A Video Showcase
curl -s -X POST $API/widgets -H "$H" -H "Content-Type: application/json" \
-d '{"type":"video","name":"Latest videos"}'
curl -s -X POST $API/widgets/def456/sources -H "$H" -H "Content-Type: application/json" \
-d '{"provider":"youtube","ref":"https://www.youtube.com/@yourchannel","tab":"Latest"}'
curl -s -X POST $API/widgets/def456/publish -H "$H"
Limits and errors
The API enforces exactly what the dashboard does: the number of widgets per kind on your plan (and the one widget more that every paid plan holds on free terms), the logos a widget may show, the sources a tab may hold, and 5MB per image. Over a limit you get 403 with a sentence saying which, and a link to the plans. A bad key is 401, a widget that is not yours is 404, more than 600 calls in a minute is 429. Every error body is {"error":"…"} in plain words.