Module API: List, Install, Remove, and Inspect Modules

Modules are the primary extension mechanism in Space Agent. Each module lives at a logical path of the form mod/<author>/<repo>/ within one of the app layers. The module API lets you discover, install, and remove modules, and lets the frontend resolve HTML and JavaScript extension anchor points. All module endpoints delegate to server/lib/customware/module_manage.js.

Module Namespace and Layer Resolution

Module paths follow the mod/<author>/<repo>/... convention. The server resolves module requests through layered inheritance — L0 (firmware) → L1 (group) → L2 (user) — so a user-layer module at L2/alice/mod/alice/my-tool/ overrides a matching L1 or L0 module with the same mod/ path. Pass maxLayer in any request to cap resolution. For example, the admin agent shell passes maxLayer: 0 to discover only L0 firmware modules without letting user customware shadow them.

Layer	Path prefix	Can be written by
L0	`L0/_all/mod/`	System / deployment
L1	`L1/<group-id>/mod/`	Group admin
L2	`L2/<username>/mod/`	That user

When USER_FOLDER_SIZE_LIMIT_BYTES is positive, module_install clones the repo into a system temp directory first, measures its size, and quota-checks it before moving it into L2/<user>/mod/. Installs that would exceed the quota return 413.

GET /api/module_list

Lists installed modules visible to the authenticated user. Request parameters are sent as query params. Reads from shared file_index shards — typically only the readable L1 roots plus the caller’s demand-loaded L2 shard — instead of scanning the full app index.

Request (query params)

area

string

Filter by module surface area. Accepted values include l1, l2_self, l2_user, and l2_users. Cross-user or aggregated user-layer listings require admin privileges.

ownerId

string

Filter by owner username (also accepted as owner_id or username).

string

Free-text search string to narrow results by module name or description.

Response

modules

array

List of installed module records.

Show Module record fields

path

string

Logical module path, e.g. L2/alice/mod/alice/my-tool/.

name

string

Module name derived from the mod/<author>/<repo> path segment.

area

string

Layer area: l0, l1, l2_self, or l2_user.

ownerId

string

Username or group ID that owns this module.

curl -b "space_session=<token>" \
  "https://your-space-agent.example/api/module_list?area=l2_self"

{
  "modules": [
    {
      "path": "L2/alice/mod/alice/my-tool/",
      "name": "alice/my-tool",
      "area": "l2_self",
      "ownerId": "alice"
    }
  ]
}

POST /api/module_install

Installs a module from a public or authenticated Git repository into the target layer path. The server clones the repo, publishes the changed logical paths through the shared mutation flow so all workers see the new module state, and returns both the install result and the post-install module info.

Request

path

string

required

Target logical path for the module, e.g. ~/mod/alice/my-tool/ or L2/alice/mod/alice/my-tool/.

repoUrl

string

required

Git repository URL to clone. Also accepted as repo_url, repositoryUrl, or repository_url.

commit

string

Pin the install to a specific commit hash.

tag

string

Pin the install to a specific Git tag.

token

string

Optional authentication token for private repositories.

maxLayer

number

Cap the layer for the post-install module_info read. Does not affect the install target itself.

Response

requestPath

string

The logical path as supplied in the request.

action

string

Always "installed".

module

object

Post-install module info snapshot (same shape as module_info).

Show Module info fields

path

string

Resolved logical module path.

name

string

Module name.

ownerId

string

Owning user or group.

area

string

Layer area.

{
  "path": "~/mod/alice/notes-panel/",
  "repoUrl": "https://github.com/alice/notes-panel.git",
  "tag": "v1.2.0"
}

POST /api/module_remove

Removes an installed module by deleting its directory from the app tree. Returns the post-remove module_info so the caller can confirm the layer state after deletion.

Request

path

string

required

Logical module path to remove, e.g. ~/mod/alice/my-tool/.

maxLayer

number

Cap the layer for the post-remove module_info read.

Response

action

string

Always "deleted".

path

string

Resolved path that was deleted.

requestPath

string

The path as supplied in the request.

module

object

Post-remove module info (reflects whether a lower-layer module is now visible).

{ "path": "~/mod/alice/notes-panel/" }

GET /api/module_info

Returns resolved metadata for a specific module path. Pass query params directly. Uses shared-state shards for the lookup.

Request (query params)

path

string

required

Logical module path. Also accepted as modulePath or module_path.

maxLayer

number

Cap the layer for resolution.

ownerId

string

Scope the lookup to a specific user or group owner. Also accepted as owner_id or username.

includeOtherUsers

boolean

default:"false"

Include module state for other users in the response (admin only). Also accepted as include_other_users.

Response

path

string

Resolved logical module path, or null if not installed at any readable layer.

name

string

Module name segment.

ownerId

string

Owner username or group ID.

area

string

Layer area where the module was found.

curl -b "space_session=<token>" \
  "https://your-space-agent.example/api/module_info?path=mod/alice/my-tool/"

{
  "path": "L2/alice/mod/alice/my-tool/",
  "name": "alice/my-tool",
  "ownerId": "alice",
  "area": "l2_self"
}

POST /api/extensions_load

Resolves module-owned ext/... files through the layered override system. The frontend uses this endpoint to load HTML and JavaScript extension anchor points — for example, ext/html/sidebar or ext/js/hooks. Accepts both single-group and multi-group request formats.

Request — single group

extension_point

string

Base extension anchor path, e.g. ext/html/sidebar.

filters

array

Optional array of filter strings to narrow within the extension point. Defaults to ["*"].

patterns

array

Explicit array of full extension path patterns. Takes precedence over extension_point + filters.

maxLayer

number

Cap resolution to a specific layer.

Request — grouped batch

requests

array

Array of extension request groups for batched lookups.

Show Group fields

requests[].patterns

array

required

Array of extension path patterns for this group.

Response — single group

extensions

array

Resolved extension paths as strings.

Response — grouped batch

results

array

One result per input request group, in the same order.

Show Result group fields

patterns

array

Normalized input patterns for this group.

extensions

array

Resolved extension paths.

{
  "extension_point": "ext/html/sidebar",
  "filters": ["*"]
}

{
  "requests": [
    { "patterns": ["ext/html/sidebar/*"] },
    { "patterns": ["ext/js/hooks/*"] }
  ]
}

For metadata-only discovery (such as dashboard panel manifests) that only needs readable logical file paths, prefer file_paths + file_read instead of routing through extensions_load. The extensions_load endpoint is optimised for HTML and JS anchor resolution.

Server API

Module API: List, Install, Remove, and Inspect Modules

Module Namespace and Layer Resolution

GET /api/module_list

Request (query params)

Response

POST /api/module_install

Request

Response

POST /api/module_remove

Request

Response

GET /api/module_info

Request (query params)

Response

POST /api/extensions_load

Request — single group

Request — grouped batch

Response — single group

Response — grouped batch

Build docs developers (and LLMs) love

Server API

Documentation Index

​Module Namespace and Layer Resolution

​GET /api/module_list

​Request (query params)

​Response

​POST /api/module_install

​Request

​Response

​POST /api/module_remove

​Request

​Response

​GET /api/module_info

​Request (query params)

​Response

​POST /api/extensions_load

​Request — single group

​Request — grouped batch

​Response — single group

​Response — grouped batch

Build docs developers (and LLMs) love

Module Namespace and Layer Resolution

GET /api/module_list

Request (query params)

Response

POST /api/module_install

Request

Response

POST /api/module_remove

Request

Response

GET /api/module_info

Request (query params)

Response

POST /api/extensions_load

Request — single group

Request — grouped batch

Response — single group

Response — grouped batch