Registry API

The OXP registry exposes a REST API at /api/v1/ for extension resolution, download, publishing, and token management. All responses are JSON unless otherwise noted.

Base URL

https://oxp.sh/api/v1

For local development: http://localhost:3000/api/v1

Authentication

Authenticated endpoints require a Bearer token:

Authorization: Bearer oxp_<token>

Tokens are obtained via oxp login and stored at ~/.oxp/credentials.

Endpoints

Resolve Extension

GET /api/v1/extensions/{publisher}/{slug}/resolve

Returns the latest version metadata for an extension.

Get Manifest

GET /api/v1/extensions/{publisher}/{slug}/manifest

Returns the oxp.json manifest for the latest version.

Get Signature

GET /api/v1/extensions/{publisher}/{slug}/signature

Returns the Ed25519 or Sigstore signature for the latest version.

Download Bundle

GET /api/v1/extensions/{publisher}/{slug}/bundle

Returns the raw .oxp bytes. Content-Type: application/vnd.oxp.bundle.v1.tar+zstd.

List Versions

GET /api/v1/extensions/{publisher}/{slug}/versions

Returns a newest-first list of all versions with extensionId and latest marker.

Publish Version

POST /api/v1/extensions/{publisher}/{slug}/versions
Content-Type: multipart/form-data
Authorization: Bearer oxp_<token>

Multipart fields:

The endpoint validates:

1. Token scope matches publish:@{publisher}/* or publish:@{publisher}/{slug}
2. Manifest conforms to the JSON Schema
3. Bundle policy is enforced (no code in ui-v1, WIT pin for component-v1)
4. TOFU key pinning — key must match previous publishes
5. WIT pin (for component bundles) matches the server's canonical world

Publisher Keys

GET /api/v1/publishers/{handle}/keys

Returns the Ed25519 public keys registered to a publisher. Cache: max-age=5, stale-while-revalidate=10.

Token Rotation

POST /api/v1/tokens/rotate
Authorization: Bearer oxp_<token>

Mints a successor token with same or narrowed scopes. The caller token gets a 5-minute grace window before retirement. Returns the new raw secret exactly once.

Error Responses

All errors follow a consistent shape:

{
  "error": {
    "code": "BUNDLE_POLICY_VIOLATION",
    "message": "ui-v1 bundles must not contain executable code",
    "details": { "file": "ui/malicious.js" }
  }
}

Error Codes