On this page

HTTP registry endpoints

The minimum HTTP contract a Skill Wiki registry must implement. Reference impl: packages/registry/src/index.ts.

Authentication

POST endpoints require Authorization: Bearer <token>. Reads are public unless the registry chooses otherwise. Tokens are issued out-of-band; format and lifecycle are registry-specific.

Endpoints

`POST /publish`

Upload a Prime tarball + manifest.

Headers:
  Authorization: Bearer <token>
  Content-Type:  multipart/form-data

Form parts:
  manifest:  pack.yaml content (string)
  tarball:   .tar.gz binary

Response (201):
{
  "name":     "@my/prime",
  "version":  "1.0.0",
  "sha256":   "...",
  "url":      "/pack/@my/pack/1.0.0/tarball"
}

Errors:
  400  bad manifest schema
  401  bad token
  409  version already published

`GET /pack/:scope`

List versions of a Prime.

Path: /pack/%40my%2Fcooking          // url-encoded "@my/cooking"

Response (200):
{
  "name": "@my/cooking",
  "versions": [
    { "version": "1.0.0", "published_at": "2026-05-01T12:00:00Z" },
    { "version": "1.1.0", "published_at": "2026-05-08T09:30:00Z" }
  ],
  "latest": "1.1.0"
}

`GET /pack/:scope/:version`

Get the manifest of a specific version.

Response (200):
{
  "name":          "@my/cooking",
  "version":       "1.1.0",
  "description":   "Cooking knowledge ...",
  "license":       "Apache-2.0",
  "atoms":         123,
  "namespaces":    ["@my"],
  "prime-version": "1.0",
  "sha256":        "...",
  "tarball_url":   "/pack/@my/cooking/1.1.0/tarball"
}

`GET /pack/:scope/:version/tarball`

Download the Prime tarball.

Response (200):
  Content-Type: application/gzip
  Body: tarball bytes

Optional endpoints

`GET /search?q=...`

Response (200):
{
  "results": [
    {
      "name":        "@my/cooking",
      "version":     "1.1.0",
      "description": "...",
      "score":       0.84
    }
  ]
}

`DELETE /pack/:scope/:version`

Yank a version. Authenticated. Most registries SHOULD reject this for non-prereleases.

Status codes

Code	Meaning
200	OK.
201	Created (publish).
304	Not Modified (use ETag for tarballs).
400	Schema error in manifest or query.
401	Bad / missing auth.
404	Prime or version not found.
409	Version conflict on publish.
500	Server error.

Mirror / fallback

The CLI accepts multiple --remote values; on 404 the resolver falls through to the next. This makes vendor mirroring (e.g. corporate proxy in front of a public registry) trivial.

Reference implementation

packages/registry/src/index.ts — single-file Bun server using SQLite for the manifest store and the local filesystem for tarballs. ~600 LOC.