---
title: "Helicon developer docs and public JSON API"
url: https://helicon.sh/developers
description: "The public JSON API for Helicon: releases, downloads, documentation and search. No key, no account, read only, with an OpenAPI description and structured JSON errors."
updated: 2026-09-19
site: Helicon
---

# Developer documentation

Helicon publishes a public, read-only JSON API at https://helicon.sh/api/v1. There is no key and no account: every endpoint is anonymous, CORS open and CDN cached. It is described by an OpenAPI 3.1 document at /openapi.json, and every failure returns the same JSON envelope with a stable code, a message and a hint.

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

| Thing | Value |
| --- | --- |
| Base URL | `https://helicon.sh/api/v1` |
| Authentication | None. Public, anonymous, read only |
| CORS | `Access-Control-Allow-Origin: *` on every response |
| OpenAPI | [`/openapi.json`](https://helicon.sh/openapi.json), and [`/api/openapi.yaml`](https://helicon.sh/api/openapi.yaml) |
| Format | JSON only. `Content-Type: application/json; charset=utf-8` |
| Methods | GET, HEAD and OPTIONS. Anything else answers 405 with a JSON body |

## A first request

```sh
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

| Endpoint | Operation | What it returns |
| --- | --- | --- |
| `GET /api/v1` | `getApiIndex` | Every endpoint, the auth model and the cache policy |
| `GET /api/v1/status` | `getStatus` | Liveness, plus the version currently shipping |
| `GET /api/v1/facts` | `getFacts` | Licence, price, requirements, platforms, and the claims that are false |
| `GET /api/v1/release` | `getLatestRelease` | The newest release, with an installer per platform |
| `GET /api/v1/releases` | `listReleases` | Recent releases, newest first. `limit` up to 100 |
| `GET /api/v1/downloads` | `listDownloads` | The installer for every supported platform |
| `GET /api/v1/downloads/{platform}` | `getDownload` | One platform: `windows`, `macos` or `linux` |
| `GET /api/v1/sections` | `listSections` | The documentation hubs and their page counts |
| `GET /api/v1/pages` | `listPages` | Every page. Filter with `section`, page with `limit` and `offset` |
| `GET /api/v1/pages/{slug}` | `getPage` | One page. Add `include=markdown` for the whole body |
| `GET /api/v1/search` | `searchPages` | Search titles, slugs, keywords and answers. `q` is required |
| `GET /api/v1/faq` | `listFaqs` | Every question the site answers, grouped |

_Every operation has a unique operationId, typed parameters and a response schema, so the OpenAPI document can be turned into function-calling tools without hand-written wrappers._

## 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`.

```json
{
  "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"
  }
}
```

| Code | Status | Means |
| --- | --- | --- |
| `not_found` | 404 | No endpoint or resource at that path |
| `invalid_parameter` | 400 | A query or path parameter was missing, malformed or out of range |
| `method_not_allowed` | 405 | The API is read only and the request used another method |
| `upstream_unavailable` | 503 | GitHub did not answer, so release data is unknown right now |

## 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`:

```sh
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

| URL | What it is |
| --- | --- |
| [`/openapi.json`](https://helicon.sh/openapi.json) | OpenAPI 3.1 description of the API |
| [`/api/openapi.yaml`](https://helicon.sh/api/openapi.yaml) | The same document, as YAML |
| [`/llms.txt`](https://helicon.sh/llms.txt) | The llmstxt.org index of the whole site |
| [`/llms-full.txt`](https://helicon.sh/llms-full.txt) | Every page in one plain-text file |
| [`/agents.md`](https://helicon.sh/agents.md) | How an agent should install and describe Helicon |
| [`/facts.json`](https://helicon.sh/facts.json) | The checkable facts, as JSON |
| [`/sitemap.xml`](https://helicon.sh/sitemap.xml) | Every indexable URL |
| `/<any-page>.md` | The Markdown mirror of that page |

## 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:

```sh
# 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

```sh
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.

## Frequently asked questions

### Does Helicon have a public API?

Yes. A read-only JSON API at https://helicon.sh/api/v1, with no key and no account, described by an OpenAPI 3.1 document at https://helicon.sh/openapi.json. It covers releases, installers, documentation pages, search and the FAQ.

### Do I need an API key to use the Helicon API?

No. Every endpoint is public, anonymous and read only, and CORS is open, so you can call it from a browser, a server or an agent without registering anything.

### How do I get the latest Helicon version programmatically?

GET https://helicon.sh/api/v1/status and read latest_version, or GET /api/v1/release for the full release with an installer per platform. Both return 503 rather than a stale guess when GitHub is unreachable.

### Is there a Helicon CLI on npm?

Not yet. Helicon drives Meta's muse CLI rather than shipping its own, and the repository's npm workspaces are libraries rather than a published command line tool. Everything scriptable about the website is in the public JSON API.

## Related

- [About](https://helicon.sh/about): Who builds Helicon, why a Muse Code desktop app exists at all, how it is funded, and what it deliberately is not. One maintainer, MIT licensed, no company behind it.
- [Contact](https://helicon.sh/contact): How to reach the person who maintains Helicon: email for anything private, GitHub issues for bugs and features, and a private advisory channel for security reports.
- [Remote daemon and web UI](https://helicon.sh/features/remote-daemon): The same Helicon UI ships as a web app pointed at a daemon on another machine, so a laptop can supervise Muse Code running on a workstation or a server.
- [llms.txt](https://helicon.sh/glossary/llms-txt): llms.txt is a plain text file at a site's root that gives language models a clean summary and an index of the pages worth reading. What goes in one.
- [the Muse Code Session Protocol](https://helicon.sh/glossary/msp): MSP is the JSON-RPC protocol that applications use to drive a Muse Code session over stdio, instead of parsing terminal output. What it carries and why it matters.

---

Helicon is a free, MIT licensed, unofficial community client for Meta's Muse Code CLI. Not made, sponsored or endorsed by Meta. Source: https://helicon.sh/. Machine readable index: https://helicon.sh/llms.txt