List Services belonging to a Project

GET/projects/{projectId}/services/

API version

v2

Request method

GET

Operation ID

container-list-services

---

Request

• projectIdstring (uuid)

  required

  ID of the Project to list Services for.

Responses

Response headers

• X-Pagination-Limitinteger

  The limit used to select the resources for the response

• X-Pagination-Skipinteger

  The number of skipped items

• X-Pagination-Pagenumber

  The calculate page of the list response. Refer to parameters to learn more.

• X-Pagination-TotalCountinteger

  The total amount of items available in the remote ressource. Use this value in combination with the limit to calculate the available pages.

Format

application/json

Description

OK

Schema documentation

• 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.

• imageDigeststring
• 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

messagestring

Message explaining the current state of the container. This may contain information about the current state of the container, or errors that occurred during deployment.

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.

imageDigeststring

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
]

requiresRecreateboolean

required

serviceNamestring

required

shortIdstring

required

A short ID of the container. This is a unique identifier for the container within the project, and can be used to reference it in other API calls, or for SSH connections.

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

required

statusSetAtstring (date-time)

required

]

Example

Content-Type: application/json

[
  {
    "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",
      "imageDigest": "string",
      "ports": [
        "3306:3306/tcp"
      ],
      "volumes": [
        "data:/var/lib/mysql",
        "/home/p-XXXXX/html:/var/www"
      ]
    },
    "description": "MySQL DB",
    "id": "f0f86186-0a5a-45b2-aa33-502777496347",
    "message": "Container ready",
    "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",
      "imageDigest": "string",
      "ports": [
        "3306:3306/tcp"
      ],
      "volumes": [
        "data:/var/lib/mysql",
        "/home/p-XXXXX/html:/var/www"
      ]
    },
    "requiresRecreate": true,
    "serviceName": "mysql-db",
    "shortId": "c-12e4u6",
    "status": "running",
    "statusSetAt": "2025-09-23T00:30:28.422Z"
  }
]

JSON Schema

{
  "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"
          },
          "imageDigest": {
            "type": "string"
          },
          "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"
      },
      "message": {
        "example": "Container ready",
        "type": "string",
        "description": "Message explaining the current state of the container. This may contain information about the current state of the container, or errors that occurred during deployment.\n"
      },
      "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"
          },
          "imageDigest": {
            "type": "string"
          },
          "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"
      },
      "requiresRecreate": {
        "type": "boolean"
      },
      "serviceName": {
        "example": "mysql-db",
        "type": "string"
      },
      "shortId": {
        "example": "c-12e4u6",
        "type": "string",
        "description": "A short ID of the container. This is a unique identifier for the container within the project, and can be used to reference it in other API calls, or for SSH connections.\n"
      },
      "status": {
        "enum": [
          "running",
          "stopped",
          "restarting",
          "error",
          "creating",
          "starting"
        ],
        "type": "string"
      },
      "statusSetAt": {
        "format": "date-time",
        "type": "string"
      }
    },
    "required": [
      "id",
      "stackId",
      "projectId",
      "description",
      "serviceName",
      "pendingState",
      "deployedState",
      "status",
      "shortId",
      "statusSetAt",
      "requiresRecreate"
    ],
    "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/services?stackId=f0f86186-0a5a-45b2-aa33-502777496347&status=running&requiresRecreate=true&searchTerm=string&sortOrder=descriptionAsc&limit=50&page=1

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.listServices({
  "projectId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "queryParameters": {
    "stackId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "status": "running",
    "requiresRecreate": true,
    "searchTerm": "string",
    "sortOrder": "descriptionAsc",
    "limit": 50,
    "page": 1
  }
});

assertStatus(response, 200);
  

PHP SDK

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

$request = (new ListServicesRequest(
  projectId: "f0f86186-0a5a-45b2-aa33-502777496347"
))
  ->withStackId("f0f86186-0a5a-45b2-aa33-502777496347")
  ->withStatus("running")
  ->withRequiresRecreate(true)
  ->withSearchTerm("string")
  ->withSortOrder("descriptionAsc")
  ->withLimit(50)
  ->withPage(1);
$response = $client->container()->listServices($request);

var_dump($response->getBody();