.npack archive to register a plugin, or add a version to one that
already exists.
Request
The form field must be namedarchive, and the filename must end in
.npack. Any other field name is ignored; a request with no archive field is
rejected.
Response
Wrapped in adata envelope, like every management API response.
files_processed uses one fixed token per entry kind, in this order:
wasm (always present), noorle, env, wit. Do not parse it for
filenames — the archive’s actual filenames are not echoed back.
Archive contents
.npack is a gzip-compressed tar archive. Entries are matched by pattern, not
by fixed filename:
Directories are skipped; anything else is ignored.
The plugin name is resolved in this order:
metadata.name from noorle.yaml,
then the archive filename minus .npack, then the WASM file’s stem.
Tool discovery does not depend on the
.wit file. Tools are extracted by
reflecting over the component’s exported functions; the WIT file, when
present, only enriches tool descriptions.Admission checks
The upload is rejected unless the WASM passes validation:- It must be a valid Component Model binary. A core WASM module is rejected.
- Every import must begin with one of nine allowed WASI prefixes:
wasi:clocks/,wasi:random/,wasi:cli/,wasi:sockets/,wasi:io/,wasi:filesystem/,wasi:http/,wasi:config/,wasi:keyvalue/. - It must export at least one callable function.
- Every WIT-derived tool name must be ASCII
[A-Za-z0-9_-], 1–64 characters, and start with a letter. A tool name outside that shape fails the upload with a 400, separately from the checks above.
noorle.yaml, when present, must declare schema_version: "1.0" exactly, and
must pass config validation.
Limits
The 50 MiB body limit is the management API’s
upload_max_size_mb setting and
is the value in effect in every shipped environment. Uploading through the
Portal enforces the same per-file size.
Validation can also produce non-blocking tool-schema warnings. When there are
any, the response carries them in a schema_warnings array alongside the
registered version — the upload still succeeds. An empty or absent
schema_warnings means validation found nothing to flag.
Activation
A newly registered version is created dormant. The upload writes the version row, pushes its metadata, and then — in a single transaction — records the content hashes and flips the active version. If that final step fails, the new version stays dormant and the previously active version keeps serving. A plugin whoseactive_version is 0 has no activated version; tool dispatch
against it fails until one is activated.
Status codes
Error bodies use the standard management API shape — see
Errors and rate limits.
There is no upload rate limit on this endpoint.