pkgs.ml
Activity Stats For agents Log in with GitHub

pkgs.ml API

The registry exposes two public surfaces: the control plane on api.pkgs.ml for publishing, search, auth, views, events, and stats; and the read plane on cdn.pkgs.ml for the sparse index, package artifacts, and Riot/OCaml distribution files.

Control plane
Authenticated and query-style routes served from https://api.pkgs.ml.

Use the control plane to search packages, fetch package views, list events, create API tokens, and publish artifacts.

Machine-readable route discovery is available at https://api.pkgs.ml/. 

curl -fsSL https://api.pkgs.ml/
CDN read plane
Sparse index and immutable download URLs served from https://cdn.pkgs.ml.

Use the CDN surface to bootstrap the sparse index, read package shard documents, and download published artifacts.

Start from https://cdn.pkgs.ml/index/v1/config.json, then read package docs and fetch artifacts via source_key. 

curl -fsSL https://cdn.pkgs.ml/index/v1/config.json
Control-plane routes
Current public routes reported by the live registry service.
Route Path
publish_artifact /v1/publish
views_package_overview /v1/views/packages/<package-name>/overview
views_package_readme /v1/views/packages/<package-name>/readme?version=<version>
views_package_examples /v1/views/packages/<package-name>/examples?version=<version>
views_package_downloads /v1/views/packages/<package-name>/downloads
views_package_relations /v1/views/packages/<package-name>/relations
views_recent_packages /v1/views/recent/packages
views_popular_packages /v1/views/popular/packages
views_categories /v1/views/categories
views_owner_packages /v1/views/owners/<github-login>/packages
views_stats_summary /v1/views/stats/summary
views_stats_dashboard /v1/views/stats/dashboard
auth_github_start /v1/auth/github/start?return_to=<url>
auth_github_callback /v1/auth/github/callback?code=<code>&state=<state>
auth_logout /v1/auth/logout
me /v1/me
tokens /v1/me/tokens
yank_release /v1/me/packages/<package-name>/versions/<version>/yank
search /v1/search?q=<query>
events /v1/events?limit=<count>&after=<event-id>
package_events /v1/packages/<package-name>/events?version=<version>&limit=<count>
CDN routes
Public immutable download and sparse-index routes.
Route Path
index_config /index/v1/config.json
index_package /index/v1/<sharded-package-document>.json
artifact_download /<artifact-key>
riot_latest_metadata /riot/latest.json
riot_release_metadata /riot/riot-<version>.json
Examples
Minimal requests for search, publishing, and route discovery.
Search
curl -fsSL 'https://api.pkgs.ml/v1/search?q=std'
Publish artifact
curl -X POST https://api.pkgs.ml/v1/publish \
  -H "Authorization: Bearer <publish-token>" \
  -H "Content-Type: application/gzip" \
  --data-binary @package.tar.gz
Client model
How third-party clients should think about the registry surface.

For package resolution, start from the sparse index config on cdn.pkgs.ml, then read package documents from the shard path and fetch package artifacts by joining artifact_base_url and the release source_key.

For publishing, create a package-root tar.gz with tusk.toml at archive root and upload it to POST /v1/publish with a bearer token.

For agents and non-human clients, see /llms.txt.

Schemas
Public document shapes for the main control-plane and CDN endpoints.

Service discovery

GET https://api.pkgs.ml/

Machine-readable root document listing the live route surface.

Field Type Notes
service string Registry service identifier.
routes object Current control-plane routes keyed by purpose.
cdn_routes object Current CDN/index/download routes keyed by purpose.
legacy_routes object Backwards-compatible aliases still served.
cdn_base_url string Base URL for CDN-backed public reads.
index_base_url string Base URL for sparse-index reads.
Example
{
  "service": "riot-package-registry",
  "routes": {
    "publish_artifact": "/v1/publish",
    "search": "/v1/search?q=<query>",
    "views_package_overview": "/v1/views/packages/<package-name>/overview",
    "views_package_examples": "/v1/views/packages/<package-name>/examples?version=<version>"
  },
  "cdn_routes": {
    "index_config": "/index/v1/config.json",
    "index_package": "/index/v1/<sharded-package-document>.json",
    "artifact_download": "/<artifact-key>"
  },
  "legacy_routes": {
    "publish_artifact": "/api/v1/publish"
  },
  "cdn_base_url": "https://cdn.pkgs.ml",
  "index_base_url": "https://cdn.pkgs.ml/index/v1"
}

Search results

GET https://api.pkgs.ml/v1/search?q=<query>

Free-text package search over package names and indexed metadata.

Field Type Notes
query string The user query echoed back.
count number Total matching packages returned.
results SearchResult[] Search hits ordered by registry ranking.
results[].package_name string Published package name.
results[].latest_version string Latest version currently indexed.
results[].description string | null Latest package description.
results[].license string | null Latest package license.
results[].repository string | null Package repository URL, if present.
results[].updated_at string Last update timestamp.
Example
{
  "query": "std",
  "count": 1,
  "results": [
    {
      "package_name": "std",
      "normalized_name": "std",
      "latest_version": "0.1.0",
      "description": "Riot standard library",
      "license": "Apache-2.0",
      "homepage": null,
      "repository": "https://github.com/leostera/riot",
      "root_module": "Std",
      "canonical_locator": "github.com/leostera/riot/packages/std",
      "repo_url": "https://github.com/leostera/riot",
      "repo_owner": "leostera",
      "repo_name": "riot",
      "subdir": "packages/std",
      "release_count": 1,
      "updated_at": "2026-04-04T09:00:00.000Z"
    }
  ]
}

Publish response

POST https://api.pkgs.ml/v1/publish

Response returned after successfully publishing a package-root artifact.

Field Type Notes
packageName string Published package name.
packageVersion string Published package version.
artifactSha256 string Immutable digest of the install artifact.
sourceKey string Artifact storage key under the CDN surface.
manifestKey string Manifest storage key under the CDN surface.
claimKey string Package claim metadata object key.
releaseKey string Release metadata object key.
indexChanged boolean Whether the sparse index document changed.
Example
{
  "artifactSha256": "e2d91c...f6ab",
  "sourceKey": "sources/std/0.1.0/e2d91c...f6ab.tar.gz",
  "manifestKey": "packages/std/0.1.0/e2d91c...f6ab.manifest.json",
  "manifestCreated": true,
  "sourceCreated": true,
  "packageName": "std",
  "packageVersion": "0.1.0",
  "claimKey": "claims/std.json",
  "releaseKey": "releases/std/0.1.0.json",
  "claimCreated": true,
  "releaseCreated": true,
  "indexChanged": true
}

Package overview view

GET https://api.pkgs.ml/v1/views/packages/<package>/overview

Summary view used by package detail pages.

Field Type Notes
schema_version 1 Current view schema version.
package_name string Package name.
latest_version string Latest published version.
artifact_sha256 string Digest of the latest install artifact.
source_key string Artifact download key for the latest release.
owner_github_login string Owning GitHub login shown on package pages.
release_count number Total published versions.
dependency_count number Direct dependency count for the latest release.
dependent_count number Indexed dependents count.
download_count number All-time package downloads recorded.
categories string[] Indexed categories.
keywords string[] Indexed keywords.
Example
{
  "schema_version": 1,
  "package_name": "kernel",
  "latest_version": "0.0.1",
  "updated_at": "2026-04-04T09:00:00.000Z",
  "published_at": "2026-04-04T09:00:00.000Z",
  "description": "Kernel package",
  "license": "Apache-2.0",
  "canonical_locator": "github.com/leostera/riot/packages/kernel",
  "repo_url": "https://github.com/leostera/riot",
  "subdir": "packages/kernel",
  "source_key": "sources/kernel/0.0.1/abc123.tar.gz",
  "manifest_key": "packages/kernel/0.0.1/abc123.manifest.json",
  "artifact_sha256": "abc123",
  "owner_github_login": "leostera",
  "release_count": 1,
  "dependency_count": 3,
  "dependent_count": 5,
  "download_count": 42,
  "categories": [
    "systems"
  ],
  "keywords": [
    "runtime",
    "kernel"
  ]
}

Package examples view

GET https://api.pkgs.ml/v1/views/packages/<package>/examples?version=<version>

Runnable example sources discovered from the published package artifact.

Field Type Notes
schema_version 1 Current view schema version.
package_name string Package name.
package_version string Resolved package version.
source_key string Install artifact key containing the example files.
examples PackageExampleDocument[] Artifact-backed example sources for this release.
examples[].name string Example binary name derived from the file basename.
examples[].path string Relative path to the example source inside the artifact.
examples[].source_code string Raw example source file contents.
Example
{
  "schema_version": 1,
  "package_name": "actors",
  "package_version": "0.0.4",
  "source_key": "sources/actors/0.0.4/abc123.tar.gz",
  "examples": [
    {
      "name": "ping_pong",
      "path": "examples/ping_pong.ml",
      "source_code": "let () = print_endline \"pong\"\\n"
    }
  ]
}

Package downloads view

GET https://api.pkgs.ml/v1/views/packages/<package>/downloads

Download graph data for the package detail page.

Field Type Notes
schema_version 1 Current view schema version.
package_name string Package name.
latest_version string Latest published version.
window_days number Number of days included in daily_downloads.
total_downloads number All-time downloads recorded for the package.
daily_downloads PackageDailyDownloadPoint[] One point per day in the selected window.
version_downloads PackageVersionDownloadPoint[] Per-version all-time download counts.
Example
{
  "schema_version": 1,
  "package_name": "kernel",
  "latest_version": "0.0.1",
  "generated_at": "2026-04-04T09:00:00.000Z",
  "window_days": 30,
  "total_downloads": 42,
  "daily_downloads": [
    {
      "date": "2026-04-02",
      "download_count": 3
    },
    {
      "date": "2026-04-03",
      "download_count": 9
    },
    {
      "date": "2026-04-04",
      "download_count": 30
    }
  ],
  "version_downloads": [
    {
      "version": "0.0.1",
      "published_at": "2026-04-04T09:00:00.000Z",
      "download_count": 42,
      "is_latest": true
    }
  ]
}

Package relations view

GET https://api.pkgs.ml/v1/views/packages/<package>/relations

Dependencies and dependents for a package.

Field Type Notes
schema_version 1 Current view schema version.
package_name string Package name.
updated_at string Time the view was generated.
dependencies PackageRelationDependency[] Direct dependencies with registry requirement strings.
dependents PackageRelationDependent[] Packages that currently depend on this package.
Example
{
  "schema_version": 1,
  "package_name": "kernel",
  "updated_at": "2026-04-04T09:00:00.000Z",
  "dependencies": [
    {
      "package_name": "std",
      "requirement": "*"
    }
  ],
  "dependents": [
    {
      "package_name": "actors",
      "latest_version": "0.0.1",
      "requirement": "*"
    }
  ]
}

Registry events

GET https://api.pkgs.ml/v1/events?limit=<count>&after=<event-id>

Chronological package publication, indexing, and post-publish pipeline activity.

Field Type Notes
limit number | undefined Requested page size.
after string | undefined Cursor-style event id for polling newer events.
events RegistryEventRecord[] Newest-first event list.
events[].event_type string One of package.submitted, package.verified, package.published, package.indexed, package.searchable, package.processing.queued, package.processing.started, package.processing.requeued, package.processing.blocked, package.processing.finished, package.docs.staged, package.docs.generated, package.docs.failed, package.build.staged, package.build.verified, package.build.failed.
events[].payload object Small event-specific payload used by the activity UIs.
Example
{
  "limit": 2,
  "after": "0195f6c1-3cc1-7c84-b0f4-8c7f7d7e5f3f",
  "events": [
    {
      "event_id": "0195f6c1-3d5b-7198-8f76-8d5880e66eb0",
      "event_type": "package.published",
      "package_name": "kernel",
      "package_version": "0.0.1",
      "package_locator": "github.com/leostera/riot/packages/kernel",
      "payload": {
        "artifact_sha256": "abc123",
        "dependency_count": 3
      },
      "created_at": "2026-04-04T09:00:00.000Z"
    }
  ]
}

Stats summary view

GET https://api.pkgs.ml/v1/views/stats/summary

Homepage counters and small stats summaries.

Field Type Notes
schema_version 1 Current view schema version.
generated_at string When the summary was generated.
total_package_downloads number All recorded package installs.
total_riot_downloads number All recorded Riot binary downloads.
total_ocaml_downloads number All recorded OCaml toolchain downloads.
total_packages number Published package count.
total_versions number Published version count.
total_users number Authenticated user count.
Example
{
  "schema_version": 1,
  "generated_at": "2026-04-04T09:00:00.000Z",
  "total_package_downloads": 42,
  "total_riot_downloads": 9,
  "total_ocaml_downloads": 7,
  "total_packages": 12,
  "total_versions": 19,
  "total_users": 4
}

Sparse index config

GET https://cdn.pkgs.ml/index/v1/config.json

Registry bootstrap document for sparse-index clients.

Field Type Notes
schema_version 1 Current sparse index schema version.
kind "sparse" Index format identifier.
package_path_strategy "cargo-lowercase-v1" Sharding algorithm used for package documents.
index_base_url string Base URL for package shard documents.
artifact_base_url string Base URL for artifact downloads.
Example
{
  "schema_version": 1,
  "kind": "sparse",
  "package_path_strategy": "cargo-lowercase-v1",
  "index_base_url": "https://cdn.pkgs.ml/index/v1",
  "artifact_base_url": "https://cdn.pkgs.ml"
}

Sparse package document

GET https://cdn.pkgs.ml/index/v1/<sharded-package>.json

Sparse-index package document consumed by solvers and installers.

Field Type Notes
schema_version 1 Current sparse index schema version.
name string Package name.
latest string Latest version string.
updated_at string Latest package update time.
releases IndexedPackageRelease[] All published versions kept in the sparse index.
releases[].source_key string Published install artifact key, joined with artifact_base_url.
releases[].manifest_key string Manifest object key.
releases[].artifact_sha256 string Digest of the published install artifact.
Example
{
  "schema_version": 1,
  "name": "std",
  "latest": "0.1.0",
  "updated_at": "2026-04-04T09:00:00.000Z",
  "releases": [
    {
      "version": "0.1.0",
      "published_at": "2026-04-04T09:00:00.000Z",
      "canonical_locator": "github.com/leostera/riot/packages/std",
      "repo_url": "https://github.com/leostera/riot",
      "subdir": "packages/std",
      "artifact_sha256": "abc123",
      "description": "Riot standard library",
      "license": "Apache-2.0",
      "manifest_key": "packages/std/0.1.0/abc123.manifest.json",
      "source_key": "sources/std/0.1.0/abc123.tar.gz",
      "dependencies": [
        {
          "stdlib": "*"
        }
      ]
    }
  ]
}