Marketplace API v1 (contract)

Status: documented and implemented on the client; no public server exists. Shellaro uses this API only when you add a Marketplace API source with its base URL.

All requests are GET over https, JSON responses (Content-Type: application/json), UTF-8. Shellaro sends Accept: application/json and no credentials.

GET {base}/v1/items?shellaro=<version>

The catalog. shellaro is the client's version, so the server may leave out items that cannot run on it.

{
  "schemaVersion": 1,
  "items": [ /* the same item objects as index.json (sources.md) */ ]
}

Differences from index.json: download (or package) must be an absolute https URL of the package file for version, and sha256 its checksum. Shellaro downloads it, verifies the checksum, then reviews and installs it like any other package.

A response with schemaVersion greater than 1 is refused with "update Shellaro".

Reserved for later versions

These are not called by 0.7 and are listed so a server can be built against a stable plan:

• GET {base}/v1/items/{id}: one item with all versions (versions: [{ version, engines, download, sha256, size, date, changelog }])
• GET {base}/v1/search?q=&category=&tag=&type=: server-side search
• POST {base}/v1/publish with a package body and a publisher token: the target of shellaro ext publish once a hosted Marketplace exists
• Publisher keys: GET {base}/v1/publishers/{id}/keys to offer trusting a publisher's signing keys

Server checklist

• Serve packages as immutable files; never change a published <id>-<version>.
• Compute sha256 from the exact bytes served.
• Validate uploads with shellaro ext validate (or the same rules) before listing them.