Catalog API

Package discovery, installation, publishing, and registry management.

Endpoints

Method	Path	Description
GET	`/catalog/search`	Search packages
GET	`/catalog/packages/{name}`	Package details
GET	`/catalog/packages/{name}/versions`	List versions
POST	`/catalog/install`	Install a package
POST	`/catalog/uninstall`	Uninstall a package
GET	`/catalog/installed`	List installed packages
POST	`/catalog/publish`	Publish a package
POST	`/catalog/yank`	Yank a version
GET	`/catalog/registries`	List registries
POST	`/catalog/registries`	Add a registry
PUT	`/catalog/registries/{name}`	Update a registry
DELETE	`/catalog/registries/{name}`	Remove a registry
POST	`/catalog/registries/{name}/test`	Test connectivity
GET	`/catalog/collections`	List collections
POST	`/catalog/collections`	Create a collection
GET	`/catalog/collections/{name}`	Get collection details
PUT	`/catalog/collections/{name}`	Update a collection
DELETE	`/catalog/collections/{name}`	Delete a collection
POST	`/catalog/collections/{name}/install`	Install a collection

GET /catalog/search

curl "http://localhost:4200/catalog/search?q=claims&type=competency&region=us"

Query Parameters

Param	Type	Description
`q`	string	Search query
`type`	string	Package type filter
`domain`	string	Taxonomy domain filter
`region`	string	Region filter

Response (200)

{
  "results": [
    {
      "name": "claims-intake",
      "type": "competency",
      "version": "1.2.0",
      "description": "FNOL processing for auto/property"
    }
  ]
}

GET /catalog/packages/{name}

curl http://localhost:4200/catalog/packages/claims-intake

Response (200)

{
  "name": "claims-intake",
  "type": "competency",
  "latest_version": "1.2.0",
  "description": "First Notice of Loss processing",
  "license": "MIT",
  "author": {"name": "Insurance Corp", "email": "platform@company.com"},
  "dependencies": {"document-ocr": "^1.0", "postgresql-connector": "^2.0"},
  "keywords": ["insurance", "claims", "fnol"],
  "regions": ["us", "uk"]
}

POST /catalog/install

curl -X POST http://localhost:4200/catalog/install \
  -H "Content-Type: application/json" \
  -d '{"package": "claims-intake", "version": "1.2.0"}'

Request Body

Field	Type	Required	Description
`package`	string	Yes	Package name
`version`	string	No	Specific version (latest if omitted)

Response (200)

{
  "installed": "claims-intake@1.2.0",
  "dependencies_installed": ["document-ocr@1.4.0", "postgresql-connector@2.1.0"]
}

POST /catalog/uninstall

curl -X POST http://localhost:4200/catalog/uninstall \
  -H "Content-Type: application/json" \
  -d '{"package": "claims-intake"}'

Response (200)

{"uninstalled": "claims-intake@1.2.0"}

GET /catalog/installed

curl http://localhost:4200/catalog/installed

Response (200)

{
  "packages": [
    {"name": "claims-intake", "type": "competency", "version": "1.2.0"},
    {"name": "document-ocr", "type": "tool", "version": "1.4.0"},
    {"name": "postgresql-connector", "type": "tool", "version": "2.1.0"}
  ]
}

POST /catalog/publish

Publish a package to a registry.

curl -X POST http://localhost:4200/catalog/publish \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp/claims-intake-1.2.0.hpkg", "registry": "internal"}'

Response (200)

{"published": "claims-intake@1.2.0", "registry": "internal"}

POST /catalog/yank

Deprecate a published version (won't be installed by new users).

curl -X POST http://localhost:4200/catalog/yank \
  -H "Content-Type: application/json" \
  -d '{"package": "claims-intake", "version": "1.0.0"}'

Response (200)

{"yanked": "claims-intake@1.0.0"}

GET /catalog/registries

curl http://localhost:4200/catalog/registries

Response (200)

{
  "registries": [
    {"name": "default", "url": "https://catalog.hoziron.com", "priority": 100, "enabled": true},
    {"name": "internal", "url": "https://packages.internal.company.com", "priority": 50, "enabled": true}
  ]
}

POST /catalog/registries

curl -X POST http://localhost:4200/catalog/registries \
  -H "Content-Type: application/json" \
  -d '{
    "name": "internal",
    "url": "https://packages.internal.company.com",
    "priority": 50,
    "auth_token_env": "INTERNAL_REGISTRY_TOKEN"
  }'

Response (201)

{"name": "internal", "added": true}

POST /catalog/registries/{name}/test

curl -X POST http://localhost:4200/catalog/registries/internal/test

Response (200)

{"name": "internal", "reachable": true, "latency_ms": 45}