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, and each key may make 120 calls a minute.
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","name":"…","settings":{…}}. Starts from the standard design; any settings you pass are laid over it. |
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, 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 120 calls in a minute is 429. Every error body is {"error":"…"} in plain words.