Pulli Developer Portal

REST API reference for the Pulli macOS download manager

Pulli exposes a REST API for release information, app updates, download distribution, public statistics, license management, and billing. The API is hosted at https://pulli.app. There is no separate user login — the free license key is the account.

OpenAPI Spec (JSON)llms.txt

Authentication

Pulli uses three authentication tiers depending on the endpoint:

None
Public endpoints (health, releases, stats, downloads) require no authentication. Rate limited by IP.
License key in body
Account management endpoints require a licenseKey field in the JSON request body. The license key format is pulli-XXXX-XXXX-XXXX.
App auth
Device-scoped endpoints (validate, deactivate) require an x-machine-uid header and a signed request body. The signing token (requestSignToken) is returned during license activation. The signature is Ed25519-based and verified server-side on every request.

Release channels

Pulli publishes two release channels:

stable
Production releases. The default channel for all endpoints. Available via /api/download and /api/app/update.
nightly
Pre-release builds for testing. Pass ?channel=nightly to release and update endpoints.

API reference

All endpoints return JSON unless noted otherwise (download endpoints stream binary data). The full machine-readable spec is available at /openapi.json.

Public

Method Path Description Auth
GET/api/healthService health check (database, KV, environment)None
GET/api/statsPublic install/download statistics, cached 1 hourNone
POST/api/eventTrack a page_view or download eventNone

Releases

Method Path Description Auth
GET/api/releasesList releases, optionally filtered by ?channel=stable|nightlyNone
GET/api/get-latest-versionGet the latest released version numberNone
GET/api/download?arch=x86_64|aarch64Download the latest DMG installer (supports range requests)None
GET/api/check-update?arch&version&channelCheck for app updates; 204 if up-to-date, 200 with signature+URL if update availableNone
GET/api/app/update?arch&channelDownload the update tarball (.tar.gz) for the auto-updaterNone

Accounts

Method Path Description Auth
POST/api/v1/accounts/generateGenerate a free license key (pulli-XXXX-XXXX-XXXX)None
POST/api/v1/accounts/recoverRecover license key by emailNone
POST/api/v1/accounts/statusCheck license type, status, devices, and emailLicense key in body
POST/api/v1/accounts/emailAttach or update the email on a licenseLicense key in body
POST/api/v1/accounts/deletePermanently delete account and all associated dataLicense key in body

Licenses

Method Path Description Auth
POST/api/v1/licenses/activateActivate a license on a device; returns a requestSignToken for authenticated callsNone
POST/api/v1/licenses/validateValidate the authenticated device's licenseApp auth (x-machine-uid + signed body)
POST/api/v1/licenses/deactivateRemove the device activation for the authenticated machineApp auth (x-machine-uid + signed body)

Billing

Method Path Description Auth
POST/api/v1/billing/checkoutCreate a Polar.sh checkout URL for upgrading to ProLicense key in body

Rate limits

All endpoints are rate limited. Public endpoints are limited by IP. Account and license endpoints have per-hour buckets. If you hit a rate limit, the API returns 429 Too Many Requests with a Retry-After header.

Example requests

Check for updates 

GET /api/check-update?arch=aarch64&version=1.1.0&channel=stable

# 200 — update available
{ "version": "1.2.0", "signature": "...", "url": "..." }

# 204 — up to date

Generate a free license 

POST /api/v1/accounts/generate

{ "success": true, "data": { "licenseKey": "pulli-XXXX-XXXX-XXXX" } }

Activate a license 

POST /api/v1/licenses/activate
Content-Type: application/json

{ "licenseKey": "pulli-XXXX-XXXX-XXXX", "machineUid": "abc123", "platform": "darwin", "appVersion": "1.2.0" }

{ "success": true, "data": { "key": "pulli-XXXX-XXXX-XXXX", "licenseType": "free", "requestSignToken": "..." } }

List releases 

GET /api/releases?channel=stable

[{ "version": "1.2.0", "channel": "stable", "notes": "...", "summary": "...", "createdAt": "2025-07-01T..." }]

Resources