List Services the executing user has access to

GET/v2/services

API version

Request method

GET

Operation ID

container-list-accessible-services

Request

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

Array[
- *object
  - deployobject
    - resourcesobject
      - limits
        cpusstring
        CPU limit for the container. The value can be specified as a decimal number, where 1 corresponds to one full CPU core. For example, 0.5 means that the container is limited to using half of a CPU core.
        memorystring
        Memory limit for the container. The value can be specified in bytes or using a suffix to indicate the unit.
        
        The format matches the one used by Docker Compose‍:
        
        Values express a byte value as a string in {amount}{byte unit} format: The supported units are b (bytes), k or kb (kilo bytes), m or mb (mega bytes) and g or gb (giga bytes).
  - 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
      The digest of the image that is currently deployed.
    - 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
      The digest of the image that is currently deployed.
    - 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
  - restartPolicystring (one of: no, always, on-failure, unless-stopped)
  - 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, error, creating, starting, stopping)
    required
  - statusSetAtstring (date-time)
    required
  - templateIdstring
    ID of the template used to create this service, if one was used.
]

Content-Type: application/json

[
  {
    "deploy": {
      "resources": {
        "limits": {
          "cpus": "0.5",
          "memory": "1gb"
        }
      }
    },
    "deployedState": {
      "command": [
        "mysqld",
        "mysqld"
      ],
      "entrypoint": [
        "docker-entrypoint.sh",
        "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/tcp",
        "3306:3306/tcp"
      ],
      "volumes": [
        "data:/var/lib/mysql:ro",
        "/home/p-XXXXX/html:/var/www",
        "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",
        "mysqld"
      ],
      "entrypoint": [
        "docker-entrypoint.sh",
        "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/tcp",
        "3306:3306/tcp"
      ],
      "volumes": [
        "data:/var/lib/mysql:ro",
        "/home/p-XXXXX/html:/var/www",
        "data:/var/lib/mysql",
        "/home/p-XXXXX/html:/var/www"
      ]
    },
    "requiresRecreate": true,
    "restartPolicy": "always",
    "serviceName": "mysql-db",
    "shortId": "c-12e4u6",
    "status": "running",
    "statusSetAt": "1985-10-26T01:21:00.000Z",
    "templateId": "string"
  }
]

{
  "items": {
    "properties": {
      "deploy": {
        "properties": {
          "resources": {
            "properties": {
              "limits": {
                "properties": {
                  "cpus": {
                    "description": "CPU limit for the container. The value can be specified as a decimal number, where `1` corresponds to\none full CPU core. For example, `0.5` means that the container is limited to using half of a CPU core.\n",
                    "example": "0.5",
                    "type": "string"
                  },
                  "memory": {
                    "description": "Memory limit for the container. The value can be specified in bytes or using a suffix to indicate\nthe unit.\n\nThe format matches the one [used by Docker Compose](https://docs.docker.com/reference/compose-file/extension/#specifying-byte-values):\n\n> Values express a byte value as a string in `{amount}{byte unit}` format: The supported units are\n`b` (bytes), `k` or `kb` (kilo bytes), `m` or `mb` (mega bytes) and `g` or `gb` (giga bytes).\n",
                    "example": "1gb",
                    "type": "string"
                  }
                }
              }
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "deployedState": {
        "description": "The actual state of the container that is currently deployed.\n",
        "properties": {
          "command": {
            "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",
              "mysqld"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "entrypoint": {
            "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",
              "docker-entrypoint.sh"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "envs": {
            "additionalProperties": {
              "type": "string"
            },
            "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"
            },
            "type": "object"
          },
          "image": {
            "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",
            "type": "string"
          },
          "imageDigest": {
            "description": "The digest of the image that is currently deployed.\n",
            "type": "string"
          },
          "ports": {
            "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/tcp",
              "3306:3306/tcp"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "volumes": {
            "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:ro",
              "/home/p-XXXXX/html:/var/www",
              "data:/var/lib/mysql",
              "/home/p-XXXXX/html:/var/www"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "image"
        ],
        "type": "object"
      },
      "description": {
        "example": "MySQL DB",
        "type": "string"
      },
      "id": {
        "format": "uuid",
        "type": "string"
      },
      "message": {
        "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",
        "example": "Container ready",
        "type": "string"
      },
      "pendingState": {
        "description": "The desired state that is waiting to be reconciled.\n",
        "properties": {
          "command": {
            "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",
              "mysqld"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "entrypoint": {
            "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",
              "docker-entrypoint.sh"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "envs": {
            "additionalProperties": {
              "type": "string"
            },
            "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"
            },
            "type": "object"
          },
          "image": {
            "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",
            "type": "string"
          },
          "imageDigest": {
            "description": "The digest of the image that is currently deployed.\n",
            "type": "string"
          },
          "ports": {
            "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/tcp",
              "3306:3306/tcp"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "volumes": {
            "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:ro",
              "/home/p-XXXXX/html:/var/www",
              "data:/var/lib/mysql",
              "/home/p-XXXXX/html:/var/www"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "image"
        ],
        "type": "object"
      },
      "requiresRecreate": {
        "type": "boolean"
      },
      "restartPolicy": {
        "enum": [
          "no",
          "always",
          "on-failure",
          "unless-stopped"
        ],
        "example": "always",
        "type": "string"
      },
      "serviceName": {
        "example": "mysql-db",
        "type": "string"
      },
      "shortId": {
        "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",
        "example": "c-12e4u6",
        "type": "string"
      },
      "status": {
        "enum": [
          "running",
          "stopped",
          "error",
          "creating",
          "starting",
          "stopping"
        ],
        "type": "string"
      },
      "statusSetAt": {
        "format": "date-time",
        "type": "string"
      },
      "templateId": {
        "description": "ID of the template used to create this service, if one was used.",
        "type": "string"
      }
    },
    "required": [
      "id",
      "stackId",
      "projectId",
      "description",
      "serviceName",
      "pendingState",
      "deployedState",
      "status",
      "shortId",
      "statusSetAt",
      "requiresRecreate"
    ],
    "type": "object"
  },
  "type": "array"
}

Format

application/json

Description

Validation Error caused by invalid input data in the request

type"ValidationError"
required
messagestring
validationErrorsarray of object
required
- Array[
  - *object
    - messagestring
      required
      The standard error message
    - pathstring
      required
      The path to the part of the data that was validated. JavaScript property access notation (e.g., ".prop[1].subProp") is used.
    - typestring
      required
      ajv validation error type (e.g. "format", "required", "type") or own validation error types
    - contextobject
      The object with the additional information about the error that can be used to create custom error messages. Keys depend on the type that failed validation (e.g. "missingProperty" for type "required")
      - *string
  ]

Content-Type: application/json

{
  "type": "ValidationError",
  "message": "Validation failed",
  "validationErrors": [
    {
      "message": "should be string",
      "path": ".address.street",
      "type": "format",
      "context": {
        "format": "email"
      }
    }
  ]
}

{
  "type": "object",
  "required": [
    "type",
    "validationErrors"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "ValidationError"
      ]
    },
    "message": {
      "type": "string",
      "example": "Validation failed"
    },
    "validationErrors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "message",
          "path",
          "type"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "The standard error message",
            "example": "should be string"
          },
          "path": {
            "type": "string",
            "description": "The path to the part of the data that was validated. JavaScript property access notation (e.g., \".prop[1].subProp\") is used.\n",
            "example": ".address.street"
          },
          "type": {
            "type": "string",
            "description": "ajv validation error type (e.g. \"format\", \"required\", \"type\") or own validation error types",
            "example": "format"
          },
          "context": {
            "type": "object",
            "example": {
              "format": "email"
            },
            "description": "The object with the additional information about the error that can be used to create custom error messages. Keys depend on the\ntype that failed validation (e.g. \"missingProperty\" for type \"required\")\n",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Format

application/json

Description

An unexpected Error that occurred while handling the request

messagestring
required
typestring
required

Content-Type: application/json

{
  "message": "Something went wrong",
  "type": "InternalServerError"
}

{
  "type": "object",
  "required": [
    "type",
    "message"
  ],
  "properties": {
    "message": {
      "type": "string",
      "example": "Something went wrong"
    },
    "type": {
      "type": "string",
      "example": "InternalServerError"
    }
  }
}

Format

application/json

Description

Your request ran into a rate limit. You have to wait until rate limit expires

messagestring
typestring

Content-Type: application/json

{
  "message": "too many requests",
  "type": "RateLimitError"
}

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "example": "too many requests"
    },
    "type": {
      "type": "string",
      "example": "RateLimitError"
    }
  }
}

Format

application/json

Description

An unexpected Error that occurred while handling the request

messagestring
required
typestring
required

Content-Type: application/json

{
  "message": "Something went wrong",
  "type": "InternalServerError"
}

{
  "type": "object",
  "required": [
    "type",
    "message"
  ],
  "properties": {
    "message": {
      "type": "string",
      "example": "Something went wrong"
    },
    "type": {
      "type": "string",
      "example": "InternalServerError"
    }
  }
}

Format

application/json

Description

An unexpected Error that occurred while handling the request

messagestring
required
typestring
required

Content-Type: application/json

{
  "message": "Something went wrong",
  "type": "InternalServerError"
}

{
  "type": "object",
  "required": [
    "type",
    "message"
  ],
  "properties": {
    "message": {
      "type": "string",
      "example": "Something went wrong"
    },
    "type": {
      "type": "string",
      "example": "InternalServerError"
    }
  }
}

Usage examples

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/services?searchTerm=string&sortOrder=descriptionAsc&limit=50&page=1

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.listAccessibleServices({
  "queryParameters": {
    "searchTerm": "string",
    "sortOrder": "descriptionAsc",
    "limit": 50,
    "page": 1
  }
});

assertStatus(response, 200);
  

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

$request = (new ListAccessibleServicesRequest())
  ->withSearchTerm("string")
  ->withSortOrder("descriptionAsc")
  ->withLimit(50)
  ->withPage(1);
$response = $client->container()->listAccessibleServices($request);

var_dump($response->getBody();
  

List Services the executing user has access to

Request​

Query parameters

Responses​

OK200

Bad Request400

Forbidden403

Too Many Requests429

Internal Server Error500

default

Usage examples​

On this page

Request

Responses

Usage examples