---
title: Modules Administration Reference
path: reference/modules-admin
status: published
---

# Modules Administration Reference

Enable, disable, and configure modules for your tenant. For the module concept, see [Modules](/docs/scaigrid/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.

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

Response:

```json
{
  "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.

```bash
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.

```bash
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.

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

Response:

```json
{
  "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.

```bash
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:

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

```json
{
  "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

| Code | Meaning |
|------|---------|
| `MODULE_NOT_FOUND` | No module with that ID installed |
| `MODULE_NOT_ENABLED` | Module is disabled for the caller's scope |
| `MODULE_DEPENDENCY_UNAVAILABLE` | A dependency module is disabled or failed |

## Related

- [Modules](/docs/scaigrid/modules) — concepts
- All [individual module pages](/docs/scaigrid/) — domain-specific admin