Project

A Project is the top-level organisational construct in ModStack. It represents a clear business boundary and groups together all infrastructure, services, and environments associated with a specific business initiative.

What is a Project?

A Project is a logical container for a single business use case. It could be an e-commerce platform, an internal analytics tool, a marketing campaign backend, or any other initiative that has its own infrastructure needs. Each Project is independent and isolated, so teams working on different initiatives never interfere with each other.

This isolation allows teams to:

Separate Billing and Cost Visibility

Resource usage is tracked and invoiced per Project, giving you clear cost visibility per initiative.

Control Access at a Business Boundary

Team members are invited at the Project level. Access never bleeds between unrelated business initiatives.

Manage Environments Independently

Each Project owns its own dev, staging, and production environments with no cross-Project interference.

Apply Governance and Policies per Initiative

Compliance controls, resource quotas, and access policies can be scoped and enforced at the Project level.

In short, a Project represents what business problem you are solving.

Hosting Model

The Hosting Model determines where a Project's infrastructure actually runs. It is set when the Project is created and cannot be changed afterwards.

Value	Description
`Hosted`	The Project's infrastructure is provisioned and run by ModStack. You do not need to bring a cloud account or manage any servers — ModStack handles it end-to-end.
`BYOC`	Bring Your Own Cloud. The Project's artifacts are deployed into infrastructure the customer owns — either an existing Kubernetes cluster or a set of individual servers. ModStack orchestrates deployments and operations; the compute and network resources are yours.

Module Store

ModStack lets you control which Modules are available to a Project via Module Stores. A Module Store is simply a curated collection of Modules.

If you want to limit what a Project can use — for example, to enforce an approved set of building blocks for a team — create a custom Module Store and associate it with the Project. If no Module Store is specified, every Module in the account is available to the Project.

API Reference

The Projects API lets you create, list, update, and delete Projects programmatically. Information on how to call the API — authentication, asynchronous operations, and error responses — is described in the API overview.

GET /v1.0/modstack/project List all projects

Returns every Project the authenticated user has access to. The response is a JSON array; no pagination wrapper.

Response — 200 OK

[
  {
    "id": "7a4c1e9e-5b62-4f9a-9c2a-3f8f4d1a9b21",
    "name": "ecommerce",
    "moduleStoreId": "b8c9d0e1-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
    "createdByUserId": "0bd1f2c3-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "hostingModel": "Hosted"
  }
]

POST /v1.0/modstack/project/create Create a project

Schedules the creation of a new Project. Returns a taskId that can be polled to observe the outcome.

Request Body

Field	Type	Description
`name`	`string`	Project name. Alphanumeric with dashes and underscores; max 25 characters. Required
`hostingModel`	`enum`	Where the project's infrastructure lives. One of `Hosted` (ModStack-hosted) or `BYOC` (bring-your-own-cloud). Required
`moduleStoreId`	`uuid`	The Module Store this project draws modules from. If omitted, the account default is used. Optional

Request Example

{
  "name": "ecommerce",
  "hostingModel": "Hosted"
}

Response — 200 OK

{
  "returnCode": { "code": "Success" },
  "taskId": "f12a3b4c-5d6e-7f80-91a2-b3c4d5e6f708"
}

POST /v1.0/modstack/project/{projectId} Update a project

Schedules an update to an existing Project. The project must be in Running state for the update to be accepted.

Path Parameters

Parameter	Type	Description
`projectId`	`uuid`	The project identifier. Required

Request Body

Field	Type	Description
`name`	`string`	Updated project name. Alphanumeric with dashes and underscores; max 25 characters. Required

Request Example

{
  "name": "ecommerce-v2"
}

Response — 200 OK

{
  "returnCode": { "code": "Success" },
  "taskId": "f12a3b4c-5d6e-7f80-91a2-b3c4d5e6f708"
}

DELETE /v1.0/modstack/project/{projectId} Delete a project

Schedules the deletion of a Project and all of its associated Environments, Services, clusters, and configuration. This action cannot be undone. The project must be in Running or Failed state.

Path Parameters

Parameter	Type	Description
`projectId`	`uuid`	The project identifier. Required

Response — 200 OK

{
  "returnCode": { "code": "Success" },
  "taskId": "f12a3b4c-5d6e-7f80-91a2-b3c4d5e6f708"
}