Developer tools

WInspo exposes a small public API for building on top of datasets, a BYO dataset format, and an embed mode with a postMessage contract. Everything below is CORS-open and requires no key.

Playground

Encode

Turn slot numbers into a base62 selection code.

Decode

Resolve a code against a dataset, including the design profile.

Public API

All endpoints answer GET and OPTIONS with Access-Control-Allow-Origin: *. Errors come back as { "error": { "code": "...", "message": "..." } }.

GET/api/datasets/{source}

Returns the full resolved dataset: items with absolute media URLs, plus optional theme config. source is a built-in dataset (kao, root) or a BYO path (byo/{user}/{repo}@{ref}).

GET/api/encode?dataset={source}&slots={0,1,2}

Encodes comma-separated slot numbers into a base62 code. Returns { "code": "7", "slots": [0, 1, 2] }.

GET/api/decode?dataset={source}&code={code}

Decodes a code against a dataset. Returns the matched items, the aggregated design profile, and an unknown flag when the code references slots missing from this dataset edition.

Dataset format

A dataset is a public GitHub repo with a winspo.json manifest at its root. Load it at /byo/{username}/{repo}@{ref} — optional winspo.config.json re-themes the app.

Each item has a stable slot (a permanent bit position) and required tags. media is optional and relative to the repo root. Never reuse a slot after deleting an item — old codes would silently decode to the wrong reference.

{
  "name": "my-dataset",
  "version": "1.0.0",
  "description": "My favorite sites.",
  "items": [
    {
      "id": 1,
      "slot": 0,
      "title": "Example",
      "url": "https://example.com/",
      "media": {
        "thumbnail": "assets/example-thumb.webp",
        "fullpage": "assets/example-fullpage.webp",
        "video": "assets/example-clip.mp4"
      },
      "tags": {
        "palette": ["bright", "warm"],
        "layout": "asymmetric",
        "motion": "medium",
        "typography": "display-serif",
        "category": "portfolio"
      }
    }
  ]
}

Embed mode

Append ?embed to any dataset or lookup URL to hide chrome and post messages to the parent window via window.parent.postMessage(msg, "*").

TypePayloadWhen
winspo:ready{ datasetSource, itemCount }on load
winspo:selection{ datasetSource, selectedItemIds }on every selection change
winspo:code{ datasetSource, code, selectedItemIds }when the user finishes