Developer documentation

Everything this site knows is available as data: which version shipped, where each installer lives, every documentation page, and every question the site answers. The API exists so that an agent integrating Helicon does not have to scrape a rendered page to find out whether a user is running an old build.

Base URL and authentication

A first request

curl -sS https://helicon.sh/api/v1
curl -sS https://helicon.sh/api/v1/status
curl -sS 'https://helicon.sh/api/v1/search?q=windows&limit=3'

The index at the base URL lists every endpoint with its operation identifier, so a client that knows nothing else can discover the rest from one request.

Endpoints

Errors

Every failure, including an unknown path and an unsupported method, returns the same envelope. Branch on error.code, show error.message to a person, and act on error.hint.

{
  "error": {
    "code": "invalid_parameter",
    "message": "The \"limit\" parameter must be between 1 and 50, and was 500.",
    "hint": "Send an integer between 1 and 50, or leave \"limit\" out to use 10.",
    "status": 400,
    "documentation_url": "https://helicon.sh/developers"
  }
}

Rate limits and caching

There is no key and no quota. Responses are served from a CDN with a shared cache lifetime between five minutes and an hour depending on the endpoint, and each one carries Cache-Control saying which. Honour it rather than polling: release data changes when a release ships, and documentation changes when the site is deployed.

Markdown instead of HTML

Every page on this site, the home page included, answers in Markdown when you ask for it. Two ways, both equivalent, both returning Content-Type: text/markdown with Vary: Accept:

curl -sS -H 'Accept: text/markdown' https://helicon.sh/
curl -sS https://helicon.sh/muse-code-gui.md

A path that does not exist answers 404 with a Markdown body that says so and links to the indexes, rather than an HTML error page you would have to parse.

Machine readable surfaces

Command line interface

Helicon does not publish its own CLI on npm today, and this page will say so until it does. The command line you need for day to day work is Meta's own muse, which Helicon drives rather than replaces. Anything scriptable about this site is in the JSON API above, and curl plus jq covers it:

# The version currently shipping
curl -sS https://helicon.sh/api/v1/status | jq -r .latest_version

# The macOS installer URL for that version
curl -sS https://helicon.sh/api/v1/downloads/macos | jq -r .asset.url

The daemon and the web app are published as npm workspaces inside the repository (@helicon/daemon, @helicon/server, @helicon/ui) and can be run from a checkout with Node 22 or newer. They are libraries rather than a command line tool, and they are not published to the public npm registry yet.

Running Helicon from source

git clone https://github.com/HarjjotSinghh/helicon
cd helicon
npm install
npm run build

Node 22 or newer is required, and on Windows that means the Windows host rather than WSL2. The muse CLI has to be installed and signed in before any of it does anything useful.