Protocol V2 · Registry V4

DSH API V2

One package protocol, one registry model and one resolver. The remote API only discovers and resolves packages; installation always executes in the local DSH runtime after explicit confirmation.

Canonical package identity

Every package is identified by (type, id). The canonical coordinate is <type>:<id>@<semver-range>. Supported types are plugin, mcp, skill, and agent. There is no implicit plugin type and no legacy github: syntax.

skill:owner/example@^1.2.0
agent:owner/agent@*
mcp:owner/server@2.0.0

Response contract

Success is always { data, meta }. Failure is always { error: { code, message, details? }, meta }. meta.request_id is present on API responses and Registry-backed endpoints also expose the active Registry revision.

{
  "data": { ... },
  "meta": {
    "request_id": "...",
    "registry_revision": "..."
  }
}

Endpoints

Method	Path	Purpose
GET	`/api/v2`	API V2 capability map
GET	`/api/v2/capabilities`	Protocol, package type and channel capabilities
GET	`/api/v2/health`	Registry V4 health and revision
GET	`/api/v2/packages?q=&type=&limit=`	Package collection
GET	`/api/v2/packages/:type/:id`	Canonical package + releases
GET	`/api/v2/packages/:type/:id/releases`	Package release history
GET	`/api/v2/packages/:type/:id/releases/:version`	One immutable release
GET	`/api/v2/search?q=&type=&limit=`	Registry V4 search
POST	`/api/v2/resolve`	Resolve package + dependency graph
POST	`/api/v2/install-plan`	Build a local-only install plan
GET	`/api/v2/publishers`	Publisher identities
GET	`/api/v2/publishers/:id`	Publisher + package portfolio
GET	`/api/v2/advisories`	Security advisories
GET	`/api/v2/advisories/:id`	Security advisory detail
GET	`/api/v2/registry/revision`	Registry V4 revision
GET	`/api/v2/registry/delta?from=:revision`	Delta negotiation / full-refresh signal
POST	`/api/v2/mcp`	MCP Tools V2 JSON-RPC endpoint

Resolve

curl -X POST "https://dsh-go.pages.dev/api/v2/resolve"   -H "Content-Type: application/json"   -d '{
  "request": {
    "type": "skill",
    "id": "owner/example",
    "range": "^1.2.0",
    "channel": "stable"
  },
  "environment": {
    "dsh_version": "1.0.0",
    "os": "linux",
    "arch": "x64"
  }
}'

The resolver returns a deterministic dependency graph, install order, aggregated permissions and a resolution_hash. Revoked, yanked and critical-advisory releases are fail-closed.

Install plan

curl -X POST "https://dsh-go.pages.dev/api/v2/install-plan"   -H "Content-Type: application/json"   -d '{"type":"skill","id":"owner/example","range":"^1.2.0","channel":"stable"}'

The returned plan contains the canonical local command dsh package install ... and dsh://package/install deep link. The API never performs the installation.

MCP Tools V2

The MCP endpoint exposes only canonical Registry V4 tools: package_search, package_get, package_releases, package_resolve, package_install_plan, publisher_get, advisory_get, and registry_status.

curl -X POST "https://dsh-go.pages.dev/api/v2/mcp"   -H "Content-Type: application/json"   -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "package_search",
    "arguments": {
      "query": "agent",
      "type": "agent",
      "limit": 10
    }
  }
}'

Distribution

Registry authority: /catalog/registry-v4.json
Sharded Distribution V2: /catalog/registry-v4/index.json
Discovery Search Index V3: /catalog/search-index-v3.json
OpenAPI: /openapi.json

Breaking upgrade policy

API V1 is removed. Clients must use API V2, Registry V4, Protocol V2 and canonical package coordinates. There is no compatibility proxy or dual-write migration surface.