API Reference
HTTP API for the niso package registry. JSON request and response bodies, except for binary uploads/downloads. All errors return { "error": "message" }.
Base URL
https://registry.niso.onlineAuthentication
Pass your API key in the Authorization header. Some endpoints require a key linked to a user (created via POST /v1/auth/login) — they authorise based on namespace membership rather than the key's scope alone.
Authorization: Bearer niso_...Scopes
Comma-separated list of action:pattern pairs. Example: push:@alice/*,pull:*,admin:*.
Packages
/v1/packagespublicList packages in the registry. Optional ?q= filters by name.
Response
[
{
"name": "@hakob/my-app",
"latest_version": "1.1.0",
"description": "My application",
"updated_at": "2026-04-10T12:00:00",
"download_count": 42
}
]/v1/packages/{name}/versionspublicList every version + architecture published for a package.
Response
[
{
"name": "@hakob/my-app",
"version": "1.1.0",
"arch": "x86_64-linux",
"size": 8421376,
"checksum": "a1b2c3...",
"uploaded_at": "2026-04-10T12:00:00",
"download_count": 17
}
]/v1/packages/{name}/{version}/manifestpublicGet the raw manifest.toml shipped with a specific version.
Response
Content-Type: text/plain
[package]
name = "@hakob/my-app"
version = "1.1.0"
…/v1/packages/{name}/{version}/{arch}publicDownload a specific .niso archive.
Response
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="my-app-1.1.0-x86_64-linux.niso"/v1/packages/{name}/latest/{arch}publicDownload the latest version for the given architecture.
Returns an X-Package-Version header indicating which version was served.
/v1/packages/{name}/{version}/{arch}API keyUpload a .niso archive. The archive's manifest.toml name and version must match the URL.
Request
Content-Type: application/octet-stream
Authorization: Bearer <key>
<binary package data>Response
{
"name": "@hakob/my-app",
"version": "1.1.0",
"arch": "x86_64-linux",
"size": 8421376,
"checksum": "a1b2c3..."
}/v1/packages/{name}/{version}/{arch}API keyDelete a specific package version + architecture.
Tags
/v1/packages/{name}/tagspublicList tag → version mappings.
Response
[
{ "tag": "stable", "version": "1.0.0" },
{ "tag": "latest", "version": "1.1.0" }
]/v1/packages/{name}/tagsAPI keyCreate or move a tag.
Request
{
"tag": "stable",
"version": "1.1.0"
}Chunks
/v1/packages/{name}/{version}/{arch}/chunkspublicGet the chunk manifest for a package — used by deduplication-aware clients to fetch only chunks they don't already have.
/v1/chunks/{hash}publicDownload an individual content-addressed chunk.
/v1/chunks/{hash}API keyUpload a single chunk (admin scope required).
Authentication
/v1/auth/registerpublicCreate a new user account. Auto-creates an @username namespace and an initial API key.
Request
{
"username": "alice",
"email": "alice@example.com",
"password": "at-least-eight-chars",
"display_name": "Alice"
}Response
{
"id": 42,
"username": "alice",
"api_key": "niso_..."
}/v1/auth/loginpublicExchange username + password for a freshly-issued API key.
Request
{
"username": "alice",
"password": "secret"
}Response
{
"api_key": "niso_...",
"username": "alice"
}/v1/auth/meuser-keyReturn the authenticated user's profile and namespaces.
Response
{
"id": 42,
"username": "alice",
"email": "alice@example.com",
"display_name": "Alice",
"created_at": "2026-04-10T12:00:00",
"verified": false,
"namespaces": ["@alice"]
}/v1/auth/meuser-keyUpdate display name and/or email.
Request
{
"display_name": "Alice A.",
"email": "alice@new.example.com"
}/v1/auth/keysAPI keyCreate an API key. The plain-text value is returned exactly once — store it immediately.
Request
{
"name": "ci-deploy",
"scope": "push:@alice/*,pull:*"
}Response
{
"id": 17,
"key": "niso_...",
"name": "ci-deploy",
"scope": "push:@alice/*,pull:*"
}/v1/auth/keysAPI keyList API keys (without the plain-text values).
Response
[
{
"id": 17,
"name": "ci-deploy",
"scope": "push:@alice/*,pull:*",
"created_at": "2026-04-10T12:00:00",
"last_used_at": "2026-04-10T14:30:00"
}
]/v1/auth/keys/{id}API keyRevoke an API key.
Namespaces
/v1/namespacesuser-keyCreate an organisation namespace (must start with @).
Request
{ "name": "@my-team" }/v1/namespaces/{name}publicGet namespace metadata and member list.
Response
{
"name": "@my-team",
"owner_id": 42,
"ns_type": "org",
"created_at": "2026-04-10T12:00:00",
"members": [
{ "username": "alice", "role": "owner" },
{ "username": "bob", "role": "member" }
]
}/v1/namespaces/{name}/membersuser-keyAdd a member to the namespace.
Caller must have admin role on the namespace.
Request
{ "username": "bob", "role": "member" }/v1/namespaces/{name}/members/{username}user-keyRemove a member. The owner cannot be removed.
System
/healthpublicHealth check. 200 if the registry is up.