Flowless Docs

Appearance

On this page

Module Hub API ​

The Module Hub is the operational surface for installing, auditing, and updating modules in Pubflow Platform.

Use it when you need to know what is installed, what changed, and whether a module is ready to run safely.

How to read this page ​

Each route is described as a plain operation so the admin workflow is easier to follow.

What it does ​

  • Discovers module manifests
  • Runs dry-run plans before execution
  • Installs or updates module components in order
  • Tracks registry state and audit events
  • Detects drift and checksum changes
  • Uses a runtime lock to avoid collisions

Route map ​

MethodPathPurpose
GET/api/v1/modules/install/statusCheck whether the hub tables exist
POST/api/v1/modules/install/dry-runSimulate hub installation
POST/api/v1/modules/install/runInstall the hub tables
GET/api/v1/modules/install/Discover available modules
GET/api/v1/modules/install/:module_id/statusInspect module health and drift
GET/api/v1/modules/install/:module_id/registryRead the registry for one module
POST/api/v1/modules/install/:module_id/dry-runPlan a module install
POST/api/v1/modules/install/:module_id/runExecute a module install
POST/api/v1/modules/install/:module_id/update/dry-runPlan targeted updates
POST/api/v1/modules/install/:module_id/updateRun targeted updates

Route details ​

Hub status and install ​

GET /api/v1/modules/install/status ​

Check whether the hub tracking tables exist.

Auth: admin/superadmin.

POST /api/v1/modules/install/dry-run ​

Simulate creating the hub tables.

Auth: admin/superadmin.

POST /api/v1/modules/install/run ​

Create the hub tables.

Auth: admin/superadmin.

Discovery ​

GET /api/v1/modules/install/ ​

Discover available modules by manifest.

Auth: admin/superadmin.

Module inspection ​

GET /api/v1/modules/install/:module_id/status ​

Inspect installation state, drift, and component health.

Auth: admin/superadmin.

GET /api/v1/modules/install/:module_id/registry ​

Read the registry and audit trail for one module.

Auth: admin/superadmin.

Module execution ​

POST /api/v1/modules/install/:module_id/dry-run ​

Plan a module install before touching the database.

Auth: admin/superadmin.

POST /api/v1/modules/install/:module_id/run ​

Execute the module install.

Auth: admin/superadmin.

Module updates ​

POST /api/v1/modules/install/:module_id/update/dry-run ​

Plan targeted updates for drifted or outdated components.

Auth: admin/superadmin.

POST /api/v1/modules/install/:module_id/update ​

Run targeted updates.

Auth: admin/superadmin.

How to use it ​

  1. Check hub status first.
  2. Run a dry-run to see what will happen.
  3. Review the plan and component order.
  4. Execute the install or update only when the plan looks safe.
  5. Inspect the registry and events after the run.

Example: check hub status ​

http
GET /api/v1/modules/install/status

Example response:

json
{
  "success": true,
  "data": {
    "installed": true,
    "tables": ["module_hub_registry", "module_hub_events"]
  }
}

Example: dry-run a module install ​

http
POST /api/v1/modules/install/blog/dry-run
Content-Type: application/json

{
  "target": "all",
  "runtime_scope": "flowless-core",
  "verify_checksum": true
}

What you should expect:

  • a component-by-component execution plan
  • the ordered dependency chain
  • whether each item is install, upgrade, repair, drift, or skip

Example response:

json
{
  "success": true,
  "data": {
    "module_id": "blog",
    "runtime_scope": "flowless-core",
    "plan": [
      { "component": "core", "action": "install" },
      { "component": "ext-comments", "action": "install" }
    ]
  }
}

Example: run a module install ​

http
POST /api/v1/modules/install/blog/run
Content-Type: application/json

{
  "target": "selected",
  "components": ["ext-comments", "ext-stats"],
  "runtime_scope": "flowless-core",
  "skip_existing": true,
  "verify_checksum": true
}

Useful notes:

  • target: "core" installs the base module only.
  • target: "selected" installs specific components and resolves dependencies.
  • target: "all" installs the full module surface.

Example: inspect module status ​

http
GET /api/v1/modules/install/blog/status

Example response:

json
{
  "success": true,
  "data": {
    "module_id": "blog",
    "status": "installed",
    "drifted": false,
    "components": []
  }
}

What to watch for ​

  • Do not run overlapping installs for the same runtime_scope:module_id.
  • Use dry-runs before updates.
  • Prefer targeted updates when only one component family changed.
  • Review the registry after every install or repair.

Next ​