📡 API Reference

Complete HTTP and WebSocket API documentation for AgentRegistry.

Overview

AgentRegistry provides a fully npm-compatible HTTP API for package management, plus admin APIs for registry control.

Base URL	Description
`http://localhost:4873`	Default server address

Registry Endpoints

Standard npm registry protocol - compatible with npm, yarn, pnpm, and bun.

Method	Endpoint	Description
GET	`/`	List all packages
GET	`/-/ping`	Health check
GET	`/{package}`	Get package metadata
GET	`/{package}/{version}`	Get specific version
GET	`/{package}/-/{tarball}.tgz`	Download tarball
PUT	`/{package}`	Publish package
DELETE	`/{package}/-/{tarball}/{rev}`	Unpublish version

Scoped Packages

Fully supported with the format @scope/package-name:

GET /@myorg/utils
PUT /@myorg/utils

Search

GET /-/v1/search?text=lodash&size=20

Returns ranked results with local packages prioritized.

Admin Endpoints

🔐 Authentication Required

All admin API endpoints (except /-/admin UI) require the X-Admin-Token header. The token is auto-injected when using the Admin Panel.

Method	Endpoint	Description
GET	`/-/admin`	Admin panel UI
GET	`/-/admin/stats`	Server stats
GET	`/-/admin/quarantine`	List quarantine
DELETE	`/-/admin/quarantine`	Clear quarantine
DELETE	`/-/admin/quarantine/{file}`	Delete file
POST	`/-/admin/quarantine/{file}/approve`	Approve file
GET	`/-/admin/cache`	List cache
DELETE	`/-/admin/cache/{name}`	Delete package
POST	`/-/admin/cache/{name}/refresh`	Force refresh

IP Allowlist

Method	Endpoint	Description
GET	`/-/admin/allowlist`	Get config & entries
PUT	`/-/admin/allowlist/config`	Update config
POST	`/-/admin/allowlist/entry`	Add IP entry
DELETE	`/-/admin/allowlist/entry/{id}`	Remove entry
PUT	`/-/admin/allowlist/entry/{id}/toggle`	Enable/disable
GET	`/-/admin/allowlist/check/{ip}`	Test IP access

WebSocket API

Real-time communication for the Admin Panel.

ws://localhost:4873/-/admin/ws?token=SESSION_TOKEN

Outgoing Messages (to server)

{ "action": "getStats", "payload": {} }
{ "action": "getQuarantine", "payload": {} }
{ "action": "getCache", "payload": {} }
{ "action": "deletePackage", "payload": { "name": "pkg" } }
{ "action": "approveQuarantine", "payload": { "file": "pkg.tgz" } }
{ "action": "getGraphRoots", "payload": {} }
{ "action": "getGraphNode", "payload": { "name": "pkg" } }

Incoming Messages (from server)

{ "type": "connected" }
{ "type": "stats", "data": { ... } }
{ "type": "quarantine", "data": { "files": [...] } }
{ "type": "cache", "data": { "packages": [...] } }
{ "type": "graphRoots", "data": { "nodes": [...] } }
{ "type": "error", "data": { "message": "..." } }

💡 Recommendation

Use WebSocket for all admin operations. It provides better performance and real-time updates compared to HTTP polling.

Response Headers

Cache Headers

Header	Values
`X-Cache`	`HIT-MEMORY`, `HIT-DISK`, `MISS`
`X-Scan-Time`	Security scan duration (e.g., `8ms`)

Security Headers

All responses include:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Content-Security-Policy: ...