List Stacks belonging to a Project

GET/projects/{projectId}/stacks/

API version

v2

Request method

GET

Operation ID

container-list-stacks

---

Request

• projectIdstring (uuid)

  required

  ID of the Project to list Stacks for.

Responses

Format

application/json

Beschreibung

OK

Schema-Dokumentation

• Array[
• *object
  • descriptionstring

    required
  • disabledboolean

    required
  • idstring (uuid)

    required
  • prefixstring

    required

    Prefix for all service-names in this stack.

  • projectIdstring (uuid)

    required
  • servicesarray of object

    A set of containers that should be started in this stack. The key is relevant for network connectivity between containers, because you can use it as DNS name to resolve this containers from other containers running in the same project (or from managed apps running in the same project).

    • Array[
    • *object
      • deployedStateobject

        required

        The actual state of the container that is currently deployed.

        • commandarray of string

          The container command (equivalent to the Docker cmd). When omitted, this defaults to the command defined in the image.

          • Array[
          • *string
          ]
      • entrypointarray of string

        The container entrypoint (equivalent to the Docker entrypoint). When omitted, this defaults to the entrypoint defined in the image.

        • Array[
        • *string
        ]
    • envsobject

      Key-value map of environment variables that should be passed into the container.

      • *string
    • imagestring

      required

      The image to run, in the usual format also used by docker run and docker compose. When the image is pulled from a private registry, make sure to create it first, using the container-create-registry endpoint. The appropriate registry is matched by hostname.

    • portsarray of string

      Exposed ports. Follows the format <public-port>:<container-port>/<protocol>. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.

      • Array[
      • *string
      ]
  • volumesarray of string

    Volume mounts for this container. These items always follow the format <volume>:<mountpoint>. The <volume> may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).

    • Array[
    • *string
    ]

descriptionstring

required

idstring (uuid)

required

pendingStateobject

required

The desired state that is waiting to be reconciled.

• commandarray of string

  The container command (equivalent to the Docker cmd). When omitted, this defaults to the command defined in the image.

  • Array[
  • *string
  ]

entrypointarray of string

The container entrypoint (equivalent to the Docker entrypoint). When omitted, this defaults to the entrypoint defined in the image.

• Array[
• *string
]

envsobject

Key-value map of environment variables that should be passed into the container.

• *string

imagestring

required

The image to run, in the usual format also used by docker run and docker compose. When the image is pulled from a private registry, make sure to create it first, using the container-create-registry endpoint. The appropriate registry is matched by hostname.

portsarray of string

Exposed ports. Follows the format <public-port>:<container-port>/<protocol>. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.

• Array[
• *string
]

volumesarray of string

Volume mounts for this container. These items always follow the format <volume>:<mountpoint>. The <volume> may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).

• Array[
• *string
]

projectIdstring (uuid)

required

serviceNamestring

required

stackIdstring (uuid)

required

statusstring (one of: running, stopped, restarting, error, creating, starting)

required

]

volumesarray of object

• Array[
• *object
  • idstring (uuid)

    required
  • namestring

    required
  • orphanedboolean

    required

    Whether the Volume is attached to a Stack.

  • stackIdstring (uuid)

    required
  • storageUsageInBytesinteger

    required
  • storageUsageInBytesSetAtstring (date-time)

    required
]

]

Beispiel

[
  {
    "description": "string",
    "disabled": true,
    "id": "f0f86186-0a5a-45b2-aa33-502777496347",
    "prefix": "string",
    "projectId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "services": [
      {
        "deployedState": {
          "command": [
            "mysqld"
          ],
          "entrypoint": [
            "docker-entrypoint.sh"
          ],
          "envs": {
            "MYSQL_DATABASE": "my_db",
            "MYSQL_PASSWORD": "my_password",
            "MYSQL_ROOT_PASSWORD": "my_root_password",
            "MYSQL_USER": "my_user"
          },
          "image": "mysql:8.0",
          "ports": [
            "3306:3306/tcp"
          ],
          "volumes": [
            "data:/var/lib/mysql",
            "/home/p-XXXXX/html:/var/www"
          ]
        },
        "description": "MySQL DB",
        "id": "f0f86186-0a5a-45b2-aa33-502777496347",
        "pendingState": {
          "command": [
            "mysqld"
          ],
          "entrypoint": [
            "docker-entrypoint.sh"
          ],
          "envs": {
            "MYSQL_DATABASE": "my_db",
            "MYSQL_PASSWORD": "my_password",
            "MYSQL_ROOT_PASSWORD": "my_root_password",
            "MYSQL_USER": "my_user"
          },
          "image": "mysql:8.0",
          "ports": [
            "3306:3306/tcp"
          ],
          "volumes": [
            "data:/var/lib/mysql",
            "/home/p-XXXXX/html:/var/www"
          ]
        },
        "projectId": "f0f86186-0a5a-45b2-aa33-502777496347",
        "serviceName": "mysql-db",
        "stackId": "f0f86186-0a5a-45b2-aa33-502777496347",
        "status": "running"
      }
    ],
    "volumes": [
      {
        "id": "f0f86186-0a5a-45b2-aa33-502777496347",
        "name": "string",
        "orphaned": true,
        "stackId": "f0f86186-0a5a-45b2-aa33-502777496347",
        "storageUsageInBytes": 123,
        "storageUsageInBytesSetAt": "2024-12-19T00:33:14.720Z"
      }
    ]
  }
]

JSON Schema

{
  "items": {
    "properties": {
      "description": {
        "type": "string"
      },
      "disabled": {
        "type": "boolean"
      },
      "id": {
        "format": "uuid",
        "type": "string"
      },
      "prefix": {
        "description": "Prefix for all service-names in this stack.",
        "type": "string"
      },
      "projectId": {
        "format": "uuid",
        "type": "string"
      },
      "services": {
        "items": {
          "properties": {
            "deployedState": {
              "description": "The actual state of the container that is currently deployed.\n",
              "properties": {
                "command": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array",
                  "description": "The container command (equivalent to the [Docker cmd](https://docs.docker.com/reference/dockerfile/#cmd)). When omitted, this defaults to the command defined in the image.\n",
                  "example": [
                    "mysqld"
                  ]
                },
                "entrypoint": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array",
                  "description": "The container entrypoint (equivalent to the [Docker entrypoint](https://docs.docker.com/reference/dockerfile/#entrypoint)). When omitted, this defaults to the entrypoint defined in the image.\n",
                  "example": [
                    "docker-entrypoint.sh"
                  ]
                },
                "envs": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object",
                  "description": "Key-value map of environment variables that should be passed into the container.\n",
                  "example": {
                    "MYSQL_DATABASE": "my_db",
                    "MYSQL_PASSWORD": "my_password",
                    "MYSQL_ROOT_PASSWORD": "my_root_password",
                    "MYSQL_USER": "my_user"
                  }
                },
                "image": {
                  "type": "string",
                  "description": "The image to run, in the usual format also used by `docker run` and `docker compose`. When the image is pulled from a private registry, make sure to create it first, using the `container-create-registry` endpoint. The appropriate registry is matched by hostname.\n",
                  "example": "mysql:8.0"
                },
                "ports": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array",
                  "description": "Exposed ports. Follows the format `<public-port>:<container-port>/<protocol>`. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.\n",
                  "example": [
                    "3306:3306/tcp"
                  ]
                },
                "volumes": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array",
                  "description": "Volume mounts for this container. These items always follow the format `<volume>:<mountpoint>`. The `<volume>` may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).\n",
                  "example": [
                    "data:/var/lib/mysql",
                    "/home/p-XXXXX/html:/var/www"
                  ]
                }
              },
              "required": [
                "image"
              ],
              "type": "object"
            },
            "description": {
              "example": "MySQL DB",
              "type": "string"
            },
            "id": {
              "format": "uuid",
              "type": "string"
            },
            "pendingState": {
              "description": "The desired state that is waiting to be reconciled.\n",
              "properties": {
                "command": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array",
                  "description": "The container command (equivalent to the [Docker cmd](https://docs.docker.com/reference/dockerfile/#cmd)). When omitted, this defaults to the command defined in the image.\n",
                  "example": [
                    "mysqld"
                  ]
                },
                "entrypoint": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array",
                  "description": "The container entrypoint (equivalent to the [Docker entrypoint](https://docs.docker.com/reference/dockerfile/#entrypoint)). When omitted, this defaults to the entrypoint defined in the image.\n",
                  "example": [
                    "docker-entrypoint.sh"
                  ]
                },
                "envs": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object",
                  "description": "Key-value map of environment variables that should be passed into the container.\n",
                  "example": {
                    "MYSQL_DATABASE": "my_db",
                    "MYSQL_PASSWORD": "my_password",
                    "MYSQL_ROOT_PASSWORD": "my_root_password",
                    "MYSQL_USER": "my_user"
                  }
                },
                "image": {
                  "type": "string",
                  "description": "The image to run, in the usual format also used by `docker run` and `docker compose`. When the image is pulled from a private registry, make sure to create it first, using the `container-create-registry` endpoint. The appropriate registry is matched by hostname.\n",
                  "example": "mysql:8.0"
                },
                "ports": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array",
                  "description": "Exposed ports. Follows the format `<public-port>:<container-port>/<protocol>`. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.\n",
                  "example": [
                    "3306:3306/tcp"
                  ]
                },
                "volumes": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array",
                  "description": "Volume mounts for this container. These items always follow the format `<volume>:<mountpoint>`. The `<volume>` may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).\n",
                  "example": [
                    "data:/var/lib/mysql",
                    "/home/p-XXXXX/html:/var/www"
                  ]
                }
              },
              "required": [
                "image"
              ],
              "type": "object"
            },
            "projectId": {
              "format": "uuid",
              "type": "string"
            },
            "serviceName": {
              "example": "mysql-db",
              "type": "string"
            },
            "stackId": {
              "format": "uuid",
              "type": "string"
            },
            "status": {
              "enum": [
                "running",
                "stopped",
                "restarting",
                "error",
                "creating",
                "starting"
              ],
              "type": "string"
            }
          },
          "required": [
            "id",
            "stackId",
            "projectId",
            "description",
            "serviceName",
            "pendingState",
            "deployedState",
            "status"
          ],
          "type": "object"
        },
        "type": "array",
        "description": "A set of containers that should be started in this stack. The key is relevant for network connectivity between containers, because you can use it as DNS name to resolve this containers from other containers running in the same project (or from managed apps running in the same project).\n",
        "x-example-key": "mysql"
      },
      "volumes": {
        "items": {
          "properties": {
            "id": {
              "format": "uuid",
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "orphaned": {
              "description": "Whether the Volume is attached to a Stack.",
              "type": "boolean"
            },
            "stackId": {
              "format": "uuid",
              "type": "string"
            },
            "storageUsageInBytes": {
              "type": "integer"
            },
            "storageUsageInBytesSetAt": {
              "format": "date-time",
              "type": "string"
            }
          },
          "required": [
            "id",
            "stackId",
            "name",
            "orphaned",
            "storageUsageInBytes",
            "storageUsageInBytesSetAt"
          ],
          "type": "object"
        },
        "type": "array"
      }
    },
    "required": [
      "id",
      "projectId",
      "description",
      "disabled",
      "prefix"
    ],
    "type": "object"
  },
  "type": "array"
}

Usage examples

cURL

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/projects/f0f86186-0a5a-45b2-aa33-502777496347/stacks

JavaScript SDK

import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
  
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.container.listStacks({
  "projectId": "f0f86186-0a5a-45b2-aa33-502777496347"
});

assertStatus(response, 200);
  

PHP SDK

use \Mittwald\ApiClient\Generated\V2\Clients\Container\ListStacks\ListStacksRequest;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

$request = (new ListStacksRequest(
  projectId: "f0f86186-0a5a-45b2-aa33-502777496347"
));
$response = $client->container()->listStacks($request);

var_dump($response->getBody();