Modules Administration Reference

Enable, disable, and configure modules for your tenant. For the module concept, see Modules.

Required permission: modules:manage for enable/disable/config. modules:use is inherited from tenant_user for read access.

GET /v1/modules#

List installed modules and their status for the caller's scope.

1
2

curl https://scaigrid.scailabs.ai/v1/modules \
  -H "Authorization: Bearer $TOKEN"

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "data": [
    {
      "id": "mod_scaibot",
      "module_id": "scaibot",
      "display_name": "ScaiBot",
      "version": "1.0.0",
      "description": "Embeddable chatbot platform",
      "status": "active",
      "admin_pages": [
        {
          "page_id": "scaibot-bots",
          "title": "Bots",
          "icon": "message-square",
          "path": "/scaibot",
          "parent_nav": "Bots",
          "permission": "scaibot:bots:read"
        }
      ],
      "dependencies": [],
      "permissions": [
        {"key": "scaibot:bots:read", "display_name": "View Bots", "description": "..."}
      ],
      "frontend_url": "/static/modules/scaibot/widget.js"
    },
    ...
  ]
}

status values:

• active — module is running and handling requests
• available — module is installed but disabled for this tenant
• error — module failed to initialize (see module logs)
• disabled — explicitly disabled by a partner or tenant admin

GET /v1/modules/{module_id}#

Get a single module's details, identical to one item from the list.

POST /v1/modules/{module_id}/enable#

Enable a module for the caller's tenant.

1
2

curl -X POST https://scaigrid.scailabs.ai/v1/modules/scaibot/enable \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Enablement is scope-aware. A partner-level disable overrides a tenant-level enable — the most restrictive setting wins. Super admins can enable platform-wide.

POST /v1/modules/{module_id}/disable#

Disable a module for the caller's tenant.

1
2

curl -X POST https://scaigrid.scailabs.ai/v1/modules/scaibot/disable \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Disabled modules don't answer requests — tenant users calling the module's endpoints get 403 MODULE_NOT_ENABLED. Existing module data (bot configs, bunker snapshots, etc.) is preserved; re-enabling picks up where it left off.

GET /v1/modules/{module_id}/config#

Read the module's tenant-scoped configuration.

1
2

curl https://scaigrid.scailabs.ai/v1/modules/scaibot/config \
  -H "Authorization: Bearer $TOKEN"

Response:

1
2
3
4
5
6

{
  "data": {
    "global_config": {"default_model": "scailabs/poolnoodle-omni"},
    "scope_config": {"escalation_email": "support@acme.example"}
  }
}

• global_config — values set at the platform level. Inherited unless overridden.
• scope_config — values set for this tenant specifically. Override the global.

PUT /v1/modules/{module_id}/config#

Update the module's tenant-scoped config.

1
2
3
4

curl -X PUT https://scaigrid.scailabs.ai/v1/modules/scaibot/config \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_knowledge_top_k": 8, "escalation_email": "new@acme.example"}'

Merges into the existing scope_config. Pass null for a field to reset it to the global default.

Config shape is module-specific — see each module's page. Invalid fields return VALIDATION_ERROR.

Module status and health#

Modules that fail to initialize on startup appear with status: "error". Check the module's last error message:

1
2

curl https://scaigrid.scailabs.ai/v1/modules/{module_id} \
  -H "Authorization: Bearer $TOKEN"

1
2
3
4
5
6
7
8
9

{
  "data": {
    "status": "error",
    "last_error": {
      "message": "Redis connection refused",
      "timestamp": "2026-04-22T08:00:00Z"
    }
  }
}

Module-specific health check endpoints (e.g., ScaiInfer node heartbeats, ScaiMind cluster status) live under the module's own URL namespace.

Error codes#

Related#

• Modules — concepts
• All individual module pages — domain-specific admin