Module

If Services are the unit of deployment in ModStack, then Modules are the unit of reuse. Modules are the foundational concept behind the platform — ModStack is designed as a stack of modular components.

What is a Module?

A Module is a reusable, versioned collection of services that work together to provide a higher-level capability. Modules are:

  • Designed to work together as a coherent unit — the services inside a Module share configuration, API contracts, and data schemas. They are developed, tested, and released together as a single higher-level capability, not as a loose collection of independent services.
  • Versioned and upgradeable — every Module has an immutable version. New releases ship as new versions, and installed Modules can be upgraded in place without custom workflows or knowledge of the internal services.
  • Shareable across environments and teams — a Module is defined once at the account level and can be installed into any environment (dev, staging, prod, local) by any team member. One canonical definition, many deployments.
  • Language-agnostic — Modules are packaged as container images and configuration, so the language and runtime used by the underlying services are irrelevant to the consumer. A Module written in Go can be installed next to one written in Java or Python with no integration work. Modules expose a REST interface, so client applications and other Modules interact with them over REST regardless of the language they are written in.

For example:

  • An Authentication Module (API + database + token service)
  • An Authorization Module
  • A Metering & Billing Module
  • An Object Storage Module

Modules promote code reuse. Instead of rebuilding all this code yourself, pick a production-ready, battle-hardened Module that is already designed for the same scenario.

Modules vs Service Templates

Modules are similar to service templates, but with key differences:

Service Template Module
Defines a single service configuration Can contain multiple services
Environment-scoped Account-scoped
Used to create services Used to distribute reusable system components

A Module is more than a template — it is a distributable, upgradeable, productised unit of functionality.

Scope and Sharing

Modules exist at the account level, not the environment level. This means:

  • Once created, a Module can be shared across your team
  • Any team member can install it into their own environment
  • A Module can be deployed into multiple environments (dev, staging, prod, local)
  • Updates to the Module can be released as new versions

When a new version is published, users of the Module are notified. They can choose to upgrade, and the upgrade process does not require custom workflows or deep knowledge of internal implementation.

Modules are the primary mechanism for building reusable, composable infrastructure and application components.

Module Store

ModStack includes the concept of a Module Store — a curated collection of installable Modules.

Each account can:

  • Create one or more Module Stores
  • Curate which Modules are available
  • Restrict Modules by department or team

For example:

  • A Finance Module Store with approved billing and compliance modules
  • An Engineering Module Store with internal infrastructure components
  • A Department-specific store with restricted modules

In addition to private stores, ModStack provides a Global Module Store where:

  • Modules can be published for broader use
  • Organisations can share reusable components
  • Monetisation options are available for published Modules

This creates an ecosystem where Modules function as reusable, distributable building blocks.

API

The Module API is organised into two groups. Manage modules in an Environment covers the endpoints used to install, uninstall, and upgrade Modules inside an Environment. Create and list modules covers the endpoints used to create, list, and publish new Module definitions.

Manage modules in an Environment

These endpoints operate against a specific Environment and manage the lifecycle of a Module inside that Environment. Each call returns a taskId — the operation is executed asynchronously, and you can poll the task to track its progress.

POST /v1.0/modstack/project/{projectId}/environment/{envId}/moduleversion/install Install a module version

Installs a specific version of a Module into the target Environment. The Module is deployed as a set of Services within the Environment, and user-prompt variables defined by the Module can be supplied via userPromptValues.

Path Parameters
ParameterTypeDescription
projectId requiredUUIDThe ID of the Project that owns the Environment.
envId requiredUUIDThe ID of the Environment to install into.
Request Body
moduleVersionId UUIDrequired The ID of the Module version to install.
useEnvVariablesForUserPrompt booleanoptional If true, environment variables on the target Environment supply values for user-prompt variables. Defaults to false.
userPromptValues array<object>optional List of { name, value } objects that supply values for user-prompt input variables required by the Module. Max 10 entries.
name stringrequired Name of the user-prompt variable (must match a variable declared by the Module). Max 50 characters.
value stringrequired Value assigned to the variable. Max 1024 characters.
fileSourceValues array<object>optional Supply files from your Git repo to this Module. For example, the ModStack Identity and User Management Module can be supplied a custom theme during install. Max 10 entries.
name stringrequired Identifier for this file-source override. Max 255 characters.
serviceName stringrequired Name of the service inside the Module that this override applies to. Max 60 characters.
source CodeSourcerequired Where to pull the file from.
repoType enumrequired One of github, bitbucket, gitlab.
repo stringrequired Repository name. Max 100 characters.
branch stringrequired Git branch. Max 100 characters.
pathInRepo stringrequired Path to the file within the repo. Max 1024 characters.
sourceCodeAppInstallationId stringrequired ID of the source-code app installation (e.g. the ModStack GitHub App) that grants read access to the repo. Max 255 characters.
dataConnections objectoptional Manual DB connection overrides — one entry per service name.
resourceOverrides map<string, ServiceResources>optional Map keyed by service name. Each value overrides the CPU, RAM, and disk configuration for that service.
resourceCPUInMLimit intrequired CPU limit in millicores. Range 100–5000.
resourceRAMInMBLimit intrequired RAM limit in MB. Range 150–10240.
diskConfig DiskInfrastructureoptional Per-service disk configuration.
tempVolumeSizeInGB intoptional Size of the container's /tmp volume in GB. Range 0–50.
varlogVolumeSizeInGB intoptional Size of the container's /var/log volume in GB. Range 0–50.
disks array<object>optional Additional mounted disks. Max 10 entries. Each entry is { sizeInGB (1–100), mountPath (required, max 255) }.
Response
FieldTypeDescription
taskIdUUIDThe ID of the async task performing the install. Poll this to track progress.
returnCodeobjectStatus of the operation.
Example 
POST /v1.0/modstack/project/p-abc/environment/e-xyz/moduleversion/install
Content-Type: application/json

{
  "moduleVersionId": "mv-7f3c...",
  "userPromptValues": [
    { "name": "dbHost", "value": "db.internal" },
    { "name": "region", "value": "us-east-1" }
  ]
}
DELETE /v1.0/modstack/project/{projectId}/environment/{envId}/moduleversion/{moduleVersionId}/uninstall Uninstall a module version

Uninstalls a Module version from the target Environment. All Services that were created by this Module are removed. Fails if the specified Module version is not currently installed in the Environment, or if it is owned by an active Blueprint.

Path Parameters
ParameterTypeDescription
projectId requiredUUIDThe ID of the Project that owns the Environment.
envId requiredUUIDThe ID of the Environment to uninstall from.
moduleVersionId requiredUUIDThe ID of the installed Module version to remove.
Response
FieldTypeDescription
taskIdUUIDThe ID of the async task performing the uninstall.
returnCodeobjectStatus of the operation.
Example 
DELETE /v1.0/modstack/project/p-abc/environment/e-xyz/moduleversion/mv-7f3c/uninstall
POST /v1.0/modstack/project/{projectId}/environment/{envId}/moduleversion/{moduleVersionId}/upgrade/{newModuleVersionId} Upgrade a module version

Upgrades an installed Module from one version to another in the target Environment. By default the upgrade must move to the next sequential version; set skipVersions to true to jump versions. The upgrade runs as an async task — the response contains the taskId.

Path Parameters
ParameterTypeDescription
projectId requiredUUIDThe ID of the Project that owns the Environment.
envId requiredUUIDThe ID of the Environment that has the Module installed.
moduleVersionId requiredUUIDThe currently installed Module version.
newModuleVersionId requiredUUIDThe target Module version to upgrade to.
Request Body
skipVersions booleanoptional If true, allows skipping over intermediate versions. Defaults to false.
dataConnections objectoptional Manual DB connection overrides — one entry per service name.
resourceOverrides map<string, ServiceResources>optional Map keyed by service name. Each value overrides the CPU, RAM, and disk configuration for that service.
resourceCPUInMLimit intrequired CPU limit in millicores. Range 100–5000.
resourceRAMInMBLimit intrequired RAM limit in MB. Range 150–10240.
diskConfig DiskInfrastructureoptional Per-service disk configuration.
tempVolumeSizeInGB intoptional Size of the container's /tmp volume in GB. Range 0–50.
varlogVolumeSizeInGB intoptional Size of the container's /var/log volume in GB. Range 0–50.
disks array<object>optional Additional mounted disks. Max 10 entries. Each entry is { sizeInGB (1–100), mountPath (required, max 255) }.
Response
FieldTypeDescription
taskIdUUIDThe ID of the async task performing the upgrade.
returnCodeobjectStatus of the operation.
Example 
POST /v1.0/modstack/project/p-abc/environment/e-xyz/moduleversion/mv-7f3c/upgrade/mv-9a12
Content-Type: application/json

{
  "skipVersions": false
}

Create and list modules

These endpoints cover the creation, versioning, and publishing of Module definitions at the account level.

Module methods

CRUD operations on the Module itself — each Module is account-scoped and can have multiple versions (see Module version methods).

POST /v1.0/modstack/module/create Create a Module

Creates a new Module along with its first version. Also kicks off the initial build for the services declared in moduleConfig. The response includes a taskId that can be polled to track the build.

Request Body
name stringrequired DNS-compatible Module name. 1–30 characters, lowercase letters / digits only (no dashes).
category enumrequired One of authnandauthz, billing, storage, tasks.
region CloudRegionTypeoptional Cloud region the Module is built for (e.g. AWS_USEAST1).
supportedArchitectures array<enum>optional Target build architectures. Up to 2 of amd64, arm64.
buildComputeSize stringoptional Build-time compute tier identifier.
majorVersion intrequired Major version number (≥ 0).
minorVersion intrequired Minor version number (≥ 0).
patchVersion intrequired Patch version number (≥ 0). Must be at least 0.0.1.
moduleConfig ModuleConfigrequired Technical definition of the Module — the services it contains, plus optional lifecycle hooks and user-facing inputs.
services array<ServiceTemplate>required 1–10 Service Templates that make up this Module. Each service's name must be prefixed with <moduleName>-.
initCalls array<ModuleCall>optional Up to 5 calls executed when the Module is first installed.
configCalls array<ModuleCall>optional Up to 25 calls invoked by configure on an installed Module version.
loadConfigCall ModuleCalloptional Call used by the UI to read the current configuration of an installed Module version.
userPromptVariables array<UserPromptVariable>optional Up to 10 variables the consumer must supply at install time. Values are passed via userPromptValues when installing.
moduleTextDetails ModuleTextDetailsrequired Human-readable documentation for the Module listing page.
tagLine stringrequired Short one-line summary. Max 255 characters.
overview stringrequired Overview section (HTML allowed, no dangerous tags). Max 10,240 characters.
configuration stringrequired Configuration documentation. Max 10,240 characters.
api stringrequired API reference documentation. Max 10,240 characters.
pricing stringrequired Pricing information. Max 10,240 characters.
Response
taskId UUID ID of the async task performing the Module creation and initial build. Poll this to track progress.
returnCode object Status of the operation.
Example 
POST /v1.0/modstack/module/create
Content-Type: application/json

{
  "name": "myauth",
  "category": "authnandauthz",
  "supportedArchitectures": ["amd64", "arm64"],
  "majorVersion": 0,
  "minorVersion": 0,
  "patchVersion": 1,
  "moduleConfig": { "services": [ /* ... */ ] },
  "moduleTextDetails": {
    "tagLine": "Drop-in OIDC authentication",
    "overview": "...",
    "configuration": "...",
    "api": "...",
    "pricing": "..."
  }
}
GET /v1.0/modstack/module List Modules

Lists all Modules visible to the caller's account.

Response — array of ModuleDTO
id UUID Module ID.
name string Module name.
category enum Module category.
versions array<ModuleVersionDTO> Versions published for this Module.
GET /v1.0/modstack/module/{moduleId} Get Module details

Returns the full ModuleDTO for a specific Module, including the list of all its versions.

Path Parameters
moduleId UUIDrequired The ID of the Module.
DELETE /v1.0/modstack/module/{moduleId} Remove a Module

Removes a Module along with all of its versions. Fails if any version is still installed in an Environment.

Path Parameters
moduleId UUIDrequired The ID of the Module to remove.
Response
taskId UUID Async task performing the removal.

Module version methods

Operations on a specific version of a Module. Versioning follows semver — majorVersion.minorVersion.patchVersion.

POST /v1.0/modstack/module/{moduleId}/addversion Add a new Module version

Creates a new version of an existing Module. Takes the same moduleConfig and moduleTextDetails shape as Create Module. Kicks off a new build for the services in the version.

Path Parameters
moduleId UUIDrequired The ID of the Module.
Request Body
majorVersion intrequired Major version number (≥ 0).
minorVersion intrequired Minor version number (≥ 0).
patchVersion intrequired Patch version number (≥ 0).
moduleConfig ModuleConfigrequired Same shape as in Create Module.
moduleTextDetails ModuleTextDetailsrequired Same shape as in Create Module.
Response
taskId UUID Async task performing the version build.
GET /v1.0/modstack/module/{moduleId}/version/{moduleVersionId} Get Module version

Returns a ModuleVersionDTO containing the full configuration and text details for this version.

Path Parameters
moduleId UUIDrequired The ID of the Module.
moduleVersionId UUIDrequired The ID of the Module version.
Response — ModuleVersionDTO
id UUID The Module version ID.
version string Version string in major.minor.patch form (e.g. 1.2.0).
moduleId UUID The ID of the parent Module.
moduleName string The name of the parent Module.
status enum Current lifecycle state. One of Running, Failed, Degraded, Inactive, Creating, Building, Updating, Upgrading, Deleting, Refreshing.
config ModuleConfig The Module's technical configuration — same shape as the moduleConfig field in the Create Module request.
services array<ServiceTemplate> 1–10 Service Templates that make up this version.
initCalls array<ModuleCall> Calls executed when the Module is first installed.
configCalls array<ModuleCall> Calls exposed by configure on the installed Module version.
loadConfigCall ModuleCall Call the UI uses to read the current configuration.
userPromptVariables array<UserPromptVariable> Variables the consumer must supply when installing.
tagLineInfo string Short one-line summary (from ModuleTextDetails.tagLine).
overviewInfo string Overview section (from ModuleTextDetails.overview).
configurationInfo string Configuration documentation (from ModuleTextDetails.configuration).
apiInfo string API reference (from ModuleTextDetails.api).
pricingInfo string Pricing information (from ModuleTextDetails.pricing).
images array<ImageVersionDTO> Container images that were built for this version, one per service × region × architecture.
id UUID Image record ID.
region CloudRegionType Region this image was built for (e.g. AWS_USEAST1).
imageTag string The container image tag.
uri string Fully-qualified image URI in the container registry.
sizeInBytes long Uncompressed image size in bytes.
cmd string The image CMD (entrypoint executable).
cmdArgs string Arguments passed to cmd.
vulnerabilities array<Vulnerability> Security findings from the image scan.
POST /v1.0/modstack/module/{moduleId}/version/{moduleVersionId}/text Update text details

Updates the human-readable documentation (tagline, overview, configuration docs, API reference, pricing) for a Module version. This does not trigger a new build — only the listing text is modified.

Path Parameters
moduleId UUIDrequired The ID of the Module.
moduleVersionId UUIDrequired The ID of the Module version.
Request Body
textDetails ModuleTextDetailsrequired Updated documentation — all fields are required.
tagLine stringrequired Short one-line summary. Max 255 characters.
overview stringrequired Overview section. Max 10,240 characters.
configuration stringrequired Configuration documentation. Max 10,240 characters.
api stringrequired API reference. Max 10,240 characters.
pricing stringrequired Pricing information. Max 10,240 characters.
DELETE /v1.0/modstack/module/{moduleId}/version/{moduleVersionId} Remove a Module version

Deletes a single version of a Module. Fails if the version is installed in any Environment — first uninstall it from every Environment using the Uninstall a module version API, then call this endpoint.

Path Parameters
moduleId UUIDrequired The ID of the Module.
moduleVersionId UUIDrequired The ID of the Module version to delete.
Response
taskId UUID Async task performing the removal.
GET /v1.0/modstack/module/buildlogs/{trackingId} Download build logs

Streams the build log for a given build. Use the trackingId returned on the create / add-version task to fetch the corresponding log. A plain GET is all that's required — the server streams the body chunk-by-chunk, so the client does not need to do anything special for large logs as long as it reads the response as a stream rather than buffering it all into memory.

Response Headers
Content-Type string text/plain
Content-Encoding string gzip — the body is gzip-compressed on the fly. Most HTTP clients decompress this transparently (browsers, curl --compressed, axios, Java HttpClient, Python requests). A low-level client that doesn't honour Content-Encoding will need to pipe the body through a gzip decompressor.
Content-Disposition string inline; filename="<trackingId>.log"
Transfer-Encoding string chunked — no Content-Length is sent. The body is written as the server reads the log files, so the total size is not known up front.
Path Parameters
trackingId stringrequired Tracking ID of the build whose logs to fetch.

Handling large logs. The server does not buffer the log in memory; it reads each file and gzips the bytes straight onto the wire. Your client should do the same — write the stream to disk (or process it line-by-line) rather than calling .text() / response.content / similar APIs that load the entire body into memory. For multi-gigabyte builds this matters.

Example — curl 
# --compressed tells curl to send Accept-Encoding: gzip and
# transparently decompress the response. Redirect straight to
# a file so the body is never held in memory.
curl --compressed \
  -H "Authorization: Bearer <token>" \
  https://<host>/v1.0/modstack/module/buildlogs/<trackingId> \
  -o build.log
Example — Python (streaming) 
import requests

with requests.get(url, headers=headers, stream=True) as r:
    r.raise_for_status()
    with open("build.log", "wb") as f:
        for chunk in r.iter_content(chunk_size=64 * 1024):
            f.write(chunk)
# requests decompresses gzip automatically when stream=True,
# so "build.log" is plain text even though the wire body was gzipped.