Upload Plugin

Upload a .npack archive to register a plugin, or add a version to one that already exists.

POST https://api.noorle.com/v1/capabilities/upload
Content-Type: multipart/form-data

Request

The form field must be named archive, and the filename must end in .npack. Any other field name is ignored; a request with no archive field is rejected.

curl -X POST https://api.noorle.com/v1/capabilities/upload \
  -H "Authorization: Bearer ak-YOUR_KEY" \
  -F "archive=@dist/my-plugin.npack"

import requests

with open("dist/my-plugin.npack", "rb") as f:
    resp = requests.post(
        "https://api.noorle.com/v1/capabilities/upload",
        files={"archive": ("my-plugin.npack", f)},
        headers={"Authorization": "Bearer ak-YOUR_KEY"},
        timeout=120,
    )
result = resp.json()["data"]

const form = new FormData();
form.append("archive", npackBlob, "my-plugin.npack");

const resp = await fetch(
  "https://api.noorle.com/v1/capabilities/upload",
  {
    method: "POST",
    headers: { Authorization: "Bearer ak-YOUR_KEY" },
    body: form,
  },
);
const { data } = await resp.json();

Field	Type	Required	Notes
`archive`	file	Yes	Must have a filename ending in `.npack` and a non-empty body

Response

Wrapped in a data envelope, like every management API response.

{
  "data": {
    "capability_id": "0198f0c2-1a3d-7c41-9b2e-8f5a6d3c1e07",
    "capability_name": "my-plugin",
    "version": 2,
    "files_processed": ["wasm", "noorle", "wit"]
  }
}

Field	Type	Description
`capability_id`	UUID	The capability this version belongs to
`capability_name`	string	Resolved plugin name (see below)
`version`	integer	Version number, incremented per upload
`files_processed`	string[]	Which kinds of entry were recognized — short tokens, not filenames
`schema_warnings`	array	Non-fatal tool-schema warnings; omitted when empty

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:

Entry	Required	Matched by
The component	Yes	Any `*.wasm`. If several are present, the last one wins
Plugin config	No	`noorle.yaml` or `noorle.yml`
WIT interface	No	Any `*.wit`
Environment	No	`.env` or `env`

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.

noorle.yaml, when present, must declare schema_version: "1.0" exactly, and must pass config validation.

Limits

Limit	Value
Request body	20 MB — enforced by the server, returns 413
Advisory warning	Logged above 20 MB of WASM binary

The 20 MB 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 instead allows a larger per-file size.

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 whose active_version is 0 has no activated version; tool dispatch against it fails until one is activated.

Status codes

Code	Meaning
200	Version registered
400	Missing `archive` field, wrong extension, empty body, unreadable archive, invalid `noorle.yaml`, or failed WASM validation
403	Missing, invalid, or insufficiently privileged credential
413	Body exceeds 20 MB

Error bodies use the standard management API shape — see Errors and rate limits.

There is no upload rate limit on this endpoint.

Overview

REST API

MCP Protocol

A2A Protocol

Noorle CLI

Request

Response

Archive contents

Admission checks

Limits

Activation

Status codes

​Request

​Response

​Archive contents

​Admission checks

​Limits

​Activation

​Status codes

​Related

Request

Response

Archive contents

Admission checks

Limits

Activation

Status codes

Related