WaymakerOS Help Center

A Spark is a published HTML document with a permanent, shareable URL. It is the destination for anything you have already built — a report, a dashboard, an interactive tool, a landing page, a data visualisation. If you have a finished HTML thing and want a destination for it, it is a Spark.

Sparks are designed for the moment after creation. You use OneAI or any AI tool to build something in HTML, and then you push it to a Spark so it has a home that can be visited, shared, linked to, and updated over time. The Spark holds the HTML. The URL stays the same. You update the content by publishing a new version.

Every Spark gets a slug — a short, readable URL segment — that makes the address memorable and shareable. A Spark called "Q2 Revenue Summary" might live at sparks.waymakerone.com/q2-revenue-summary.

What a Spark is not

Sparks are one of several ways to create content in Commander. Understanding the boundaries helps you pick the right tool.

A Spark is not a Document. Documents support real-time collaboration, comments, version tracking, and rich formatting blocks like tables and embeds. Documents are where your team writes together. A Spark is a published output — it does not support inline editing by collaborators. You write the HTML elsewhere and push it to the Spark.

A Spark is not a Sheet. Sheets are structured data surfaces with typed columns, row-level permissions, formula columns, and schema-driven exports. A Spark can display data from a Table using the live binding feature, but the Spark itself has no schema. It is a presentation layer, not a data layer.

A Spark is not a Host App. Host Apps go through a build pipeline — source code, dependencies, environment variables, a deployment process, a custom domain. They are the right choice for production software your customers interact with. A Spark is much lighter: plain HTML, no build step, no dependencies, no pipeline. If you need React, a backend, or a custom domain, use a Host App. If you need to publish something immediately, use a Spark.

The mental model: if you are building software, use Host. If you are publishing a finished document or visualisation, use Sparks.

Three ways to create a Spark

1. OneAI in Commander

Open the OneAI chat inside Commander and ask it to build something. OneAI can generate HTML reports, data summaries, comparison tables, visual dashboards, and interactive tools. Once you are happy with the preview, use the "Save as Spark" action to publish it directly. OneAI handles the slug, the version metadata, and the publish — you get the URL immediately.

This is the fastest path. No file management, no upload step. Build it in the conversation, publish it in one click.

2. Paste or upload HTML

From the Sparks list view, click "New Spark" and paste your HTML into the editor, or upload an .html or .spk file from your computer. Give the Spark a name, choose a slug (or accept the auto-generated one), and publish. The content goes live within seconds.

This path suits any workflow where you generate HTML outside Commander — from a separate AI tool, from a code editor, from an export pipeline.

3. Save from any AI tool via MCP

If you use Claude Code, Cursor, or any MCP-compatible AI environment, the Waymaker MCP server includes four tools for Sparks: commander_spark_create, commander_spark_update, commander_spark_get, and commander_spark_list. Your AI agent can push HTML to a Spark directly from its working environment without leaving the tool.

This is the developer path. It means your agent can build something, test it, and publish it to a permanent URL as part of a single workflow.

Sparks use the same ShareModal as Documents and Sheets. Open any Spark, click the Share button in the top-right corner, and you will see the same sharing surface you already know.

Guest links are shareable URLs that anyone can access without a Waymaker account. You can generate a guest link for a Spark in view-only mode. The recipient clicks the link and sees the Spark rendered in their browser — no sign-in required.

View-only is the default sharing mode. Guests can view the Spark but cannot edit the underlying HTML. Only workspace members with the correct permissions can publish new versions.

Within your organisation, you can share a Spark with specific people, teams, or workspaces. Permissions follow the same model as Documents: share with a person, a role, or a team. The Spark respects whatever access level you set.

If you want to embed a Spark in an external page, the guest link is also the embed source. Use a standard <iframe> tag pointing at the guest URL.

What is a .spk file?

.spk is a Waymaker file extension for Sparks. Under the surface, it is plain HTML with a Waymaker identity extension. If you download a Spark and rename the file from .spk to .html, it will open in any browser exactly as it does inside Commander.

The .spk extension exists so that Waymaker can identify Spark files when you upload them — the upload dialog accepts both .html and .spk. It also means Spark files are easy to spot in your file system or a shared folder.

When you export a Spark using the "Download" action, you get the .spk file. You can store it locally, put it in source control, or re-upload it to any workspace. There is no proprietary binary format, no encoding, no metadata embedded in the file beyond what a standard HTML document supports.

Connecting live data (Tables binding)

A Spark can display live data from a Waymaker Table using the <meta waymaker:tables> binding pattern.

In the <head> of your HTML, declare which tables the Spark should connect to:

<meta name="waymaker:tables" content='[{"id":"tbl_xxx","access":"read"}]'>

When the Spark runs in the browser, a Waymaker shim is available as window.waymaker. Your JavaScript calls await window.waymaker.tables.read('tbl_xxx') to fetch live rows from the declared table. You can call this on page load, on a button click, or on a timer — the data comes back as a JSON array every time.

const rows = await window.waymaker.tables.read('tbl_xxx')
// rows is an array of objects — render however you like

What the shim does: The sparks-serve edge function detects the waymaker:tables meta tag and injects the shim script into the page before serving it. The shim authenticates the request using the viewer's session (or the Spark owner's credentials for guest links) and proxies table reads through the Waymaker API. No credentials are embedded in the HTML.

Security model: The shim only allows reads from tables declared in the meta tag — the Spark cannot access tables it hasn't declared. If a guest accesses a Spark via a guest link, reads run with the Spark owner's read permissions. Table data in a guest-linked Spark is effectively public — do not bind sensitive tables to a Spark you intend to share publicly. For sensitive data, keep the Spark private and share it with specific people inside your organisation.

Version history

Sparks keep the last 10 versions automatically. Every time you publish a new version — whether from OneAI, from a file upload, or from an MCP push — the previous version is stored and remains accessible.

How to restore: Open the Spark, click the three-dot menu in the top-right, and select "Version history". You will see a list of the 10 most recent versions with timestamps and optional labels. Click any version to preview it. Click "Restore" to make that version the current published version.

Version labels: When you publish a new version, you can add a short label (up to 80 characters) in the publish dialog. Labels are optional but useful — "Q2 final", "corrected revenue figures", "with client logo" are the kind of notes that make version history readable three months later.

The version cap: When you publish a new version and already have 10 versions stored, the oldest version is automatically purged. There is no way to recover a version after it has been purged. If you need to keep a specific version permanently, download the .spk file before it ages out of the 10-version window.

What is a Spark?