List app installations belonging to a Project

GET/v2/projects/{projectId}/app-installations

API version

Request method

GET

Operation ID

app-list-appinstallations

Request

projectIdstringrequired
List AppInstallations belonging to a Project.

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

Object containing the list of AppInstallations.

Array[
An AppInstallation is a concrete manifestation of an App in a specific AppVersion.
- *object
  An AppInstallation is a concrete manifestation of an App in a specific AppVersion.
  - appExternalVersionstringrequired
  - appIdstring (uuid)required
  - appNamestringrequired
  - appVersionobjectrequired
    VersionStatus describes the current and desired version of something like the AppVersion of an AppInstallation. If diverging, an internal process is going to assert, the current value will be aligned.
    - currentstring
    - desiredstringrequired
    - lastChangeBystring
    - lastChangedAtstring (date-time)
    - previousstring
  - autoUpdatesActivatedboolean
    Whether automatic updates are activated.
  - createdAtstring (date-time)required
  - customDocumentRootstring
  - deletionRequestedboolean
  - descriptionstringrequired
  - disabledbooleanrequired
  - hostnamestring
  - idstring (uuid)required
  - installationPathstringrequired
  - lastAutoUpdateFailedAtstring (date-time)
    When the last automatic update failed. Automatic updates are deactivated after a failure. The value is kept when automatic updates are activated again, so it does not indicate the current state on its own; combine it with autoUpdatesActivated (e.g. only warn while that is false).
  - lastErrorstring
    The last error that occurred during an update. Resets on success.
  - linkedDatabasesarray of objectrequired
    - Array[
      LinkedDatabase is a reference to a concrete Database and DatabaseUsers.
      - *object
        LinkedDatabase is a reference to a concrete Database and DatabaseUsers.
        databaseIdstring (uuid)required
        databaseUserIdsobject
        *string
        kindstring (one of: mysql, redis)required
        purposestring (one of: primary, cache, custom)required
      ]
  - lockedByobject
    - *string (one of: unspecified, copy)
      LockPurpose describes why a given AppInstallation is locked from deletion.
  - phasestring (one of: pending, installing, upgrading, ready, disabled, reconfiguring)required
    Phase describes the current phase/state of an AppInstallation in its lifecycle.
  - portsarray of object
    - Array[
      - *object
        namestring
        portinteger
      ]
  - projectDescriptionstringrequired
  - projectIdstring (uuid)required
  - screenshotIdstring (uuid)
  - screenshotRefstring
  - shortIdstringrequired
  - sourceAppInstallationIdstring
    The source AppInstallation ID for a staging AppInstallation.
  - stagingboolean
  - systemSoftwarearray of objectrequired
    - Array[
      InstalledSystemSoftware describes the currently configured and installed SystemSoftwareVersion of a SystemSoftware besides the desired SystemSoftwareUpdatePolicy inside an AppInstallation.
      - *object
        InstalledSystemSoftware describes the currently configured and installed SystemSoftwareVersion of a SystemSoftware besides the desired SystemSoftwareUpdatePolicy inside an AppInstallation.
        externalVersionstringrequired
        namestringrequired
        systemSoftwareIdstring (uuid)required
        systemSoftwareVersionobjectrequired
        VersionStatus describes the current and desired version of something like the AppVersion of an AppInstallation. If diverging, an internal process is going to assert, the current value will be aligned.
        currentstring
        desiredstringrequired
        lastChangeBystring
        lastChangedAtstring (date-time)
        previousstring
        updateAvailablebooleanrequired
        updatePolicystring (one of: none, inheritedFromApp, patchLevel, all)required
        SystemSoftwareUpdatePolicy describes which updates should be applied automatically by our systems.
      ]
  - updateAvailablebooleanrequired
  - updatePolicystring (one of: none, patchLevel, all)required
    AppUpdatePolicy describes which updates should be applied automatically by our systems.
  - userInputsarray of objectrequired
    - Array[
      A SavedUserInput is an entered value for a desired UserInput of an AppVersion or SystemSoftwareVersion.
      - *object
        A SavedUserInput is an entered value for a desired UserInput of an AppVersion or SystemSoftwareVersion.
        namestringrequired
        valuestringrequired
      ]
]

Content-Type: application/json

[
  {
    "appExternalVersion": "string",
    "appId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "appName": "string",
    "appVersion": {
      "current": "string",
      "desired": "string",
      "lastChangeBy": "string",
      "lastChangedAt": "1985-10-26T01:21:00.000Z",
      "previous": "string"
    },
    "autoUpdatesActivated": true,
    "createdAt": "2024-09-20T22:57:32.000Z",
    "customDocumentRoot": "string",
    "deletionRequested": true,
    "description": "string",
    "disabled": true,
    "hostname": "string",
    "id": "f0f86186-0a5a-45b2-aa33-502777496347",
    "installationPath": "string",
    "lastAutoUpdateFailedAt": "1985-10-26T01:21:00.000Z",
    "lastError": "string",
    "linkedDatabases": [
      {
        "databaseId": "f0f86186-0a5a-45b2-aa33-502777496347",
        "databaseUserIds": {
          "string": "string"
        },
        "kind": "mysql",
        "purpose": "primary"
      }
    ],
    "lockedBy": {
      "string": "unspecified"
    },
    "phase": "ready",
    "ports": [
      {
        "name": "string",
        "port": 123
      }
    ],
    "projectDescription": "string",
    "projectId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "screenshotId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "screenshotRef": "string",
    "shortId": "a-XXXXXX",
    "sourceAppInstallationId": "string",
    "staging": true,
    "systemSoftware": [
      {
        "externalVersion": "string",
        "name": "string",
        "systemSoftwareId": "f0f86186-0a5a-45b2-aa33-502777496347",
        "systemSoftwareVersion": {
          "current": "string",
          "desired": "string",
          "lastChangeBy": "string",
          "lastChangedAt": "1985-10-26T01:21:00.000Z",
          "previous": "string"
        },
        "updateAvailable": true,
        "updatePolicy": "none"
      }
    ],
    "updateAvailable": true,
    "updatePolicy": "none",
    "userInputs": [
      {
        "name": "string",
        "value": "string"
      }
    ]
  }
]

{
  "items": {
    "description": "An AppInstallation is a concrete manifestation of an App in a specific AppVersion.",
    "properties": {
      "appExternalVersion": {
        "type": "string"
      },
      "appId": {
        "format": "uuid",
        "type": "string"
      },
      "appName": {
        "type": "string"
      },
      "appVersion": {
        "description": "VersionStatus describes the current and desired version of something like the AppVersion of an AppInstallation. If diverging, an internal process is going to assert, the current value will be aligned.",
        "properties": {
          "current": {
            "type": "string"
          },
          "desired": {
            "type": "string"
          },
          "lastChangeBy": {
            "type": "string"
          },
          "lastChangedAt": {
            "format": "date-time",
            "type": "string"
          },
          "previous": {
            "type": "string"
          }
        },
        "required": [
          "desired"
        ],
        "type": "object"
      },
      "autoUpdatesActivated": {
        "description": "Whether automatic updates are activated.",
        "type": "boolean"
      },
      "createdAt": {
        "example": "2024-09-20T22:57:32.000Z",
        "format": "date-time",
        "type": "string"
      },
      "customDocumentRoot": {
        "type": "string"
      },
      "deletionRequested": {
        "default": false,
        "type": "boolean"
      },
      "description": {
        "type": "string"
      },
      "disabled": {
        "default": false,
        "type": "boolean"
      },
      "hostname": {
        "type": "string"
      },
      "id": {
        "format": "uuid",
        "type": "string"
      },
      "installationPath": {
        "type": "string"
      },
      "lastAutoUpdateFailedAt": {
        "description": "When the last automatic update failed. Automatic updates are deactivated after a failure. The value is kept when automatic updates are activated again, so it does not indicate the current state on its own; combine it with `autoUpdatesActivated` (e.g. only warn while that is false).",
        "format": "date-time",
        "type": "string"
      },
      "lastError": {
        "description": "The last error that occurred during an update. Resets on success.",
        "type": "string"
      },
      "linkedDatabases": {
        "items": {
          "description": "LinkedDatabase is a reference to a concrete Database and DatabaseUsers.",
          "properties": {
            "databaseId": {
              "format": "uuid",
              "type": "string"
            },
            "databaseUserIds": {
              "additionalProperties": {
                "type": "string"
              },
              "type": "object"
            },
            "kind": {
              "enum": [
                "mysql",
                "redis"
              ],
              "type": "string"
            },
            "purpose": {
              "enum": [
                "primary",
                "cache",
                "custom"
              ],
              "type": "string"
            }
          },
          "required": [
            "databaseId",
            "purpose",
            "kind"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "lockedBy": {
        "additionalProperties": {
          "description": "LockPurpose describes why a given AppInstallation is locked from deletion.",
          "enum": [
            "unspecified",
            "copy"
          ],
          "type": "string"
        },
        "type": "object"
      },
      "phase": {
        "description": "Phase describes the current phase/state of an AppInstallation in its lifecycle.",
        "enum": [
          "pending",
          "installing",
          "upgrading",
          "ready",
          "disabled",
          "reconfiguring"
        ],
        "example": "ready",
        "type": "string"
      },
      "ports": {
        "items": {
          "properties": {
            "name": {
              "type": "string"
            },
            "port": {
              "type": "integer"
            }
          },
          "type": "object"
        },
        "type": "array"
      },
      "projectDescription": {
        "type": "string"
      },
      "projectId": {
        "format": "uuid",
        "type": "string"
      },
      "screenshotId": {
        "format": "uuid",
        "type": "string"
      },
      "screenshotRef": {
        "type": "string"
      },
      "shortId": {
        "example": "a-XXXXXX",
        "type": "string"
      },
      "sourceAppInstallationId": {
        "description": "The source AppInstallation ID for a staging AppInstallation.",
        "type": "string"
      },
      "staging": {
        "type": "boolean"
      },
      "systemSoftware": {
        "items": {
          "description": "InstalledSystemSoftware describes the currently configured and installed SystemSoftwareVersion of a SystemSoftware besides the desired SystemSoftwareUpdatePolicy inside an AppInstallation.",
          "properties": {
            "externalVersion": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "systemSoftwareId": {
              "format": "uuid",
              "type": "string"
            },
            "systemSoftwareVersion": {
              "description": "VersionStatus describes the current and desired version of something like the AppVersion of an AppInstallation. If diverging, an internal process is going to assert, the current value will be aligned.",
              "properties": {
                "current": {
                  "type": "string"
                },
                "desired": {
                  "type": "string"
                },
                "lastChangeBy": {
                  "type": "string"
                },
                "lastChangedAt": {
                  "format": "date-time",
                  "type": "string"
                },
                "previous": {
                  "type": "string"
                }
              },
              "required": [
                "desired"
              ],
              "type": "object"
            },
            "updateAvailable": {
              "default": false,
              "type": "boolean"
            },
            "updatePolicy": {
              "description": "SystemSoftwareUpdatePolicy describes which updates should be applied automatically by our systems.",
              "enum": [
                "none",
                "inheritedFromApp",
                "patchLevel",
                "all"
              ],
              "type": "string"
            }
          },
          "required": [
            "systemSoftwareId",
            "updatePolicy",
            "systemSoftwareVersion",
            "name",
            "externalVersion",
            "updateAvailable"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "updateAvailable": {
        "default": false,
        "type": "boolean"
      },
      "updatePolicy": {
        "description": "AppUpdatePolicy describes which updates should be applied automatically by our systems.",
        "enum": [
          "none",
          "patchLevel",
          "all"
        ],
        "type": "string"
      },
      "userInputs": {
        "items": {
          "description": "A SavedUserInput is an entered value for a desired UserInput of an AppVersion or SystemSoftwareVersion.",
          "properties": {
            "name": {
              "type": "string"
            },
            "value": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "value"
          ],
          "type": "object"
        },
        "type": "array"
      }
    },
    "required": [
      "id",
      "appId",
      "shortId",
      "appVersion",
      "description",
      "installationPath",
      "disabled",
      "createdAt",
      "projectId",
      "systemSoftware",
      "userInputs",
      "updatePolicy",
      "linkedDatabases",
      "phase",
      "appName",
      "updateAvailable",
      "appExternalVersion",
      "projectDescription"
    ],
    "type": "object"
  },
  "type": "array"
}

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

messagestringrequired
typestringrequired

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/projects/string/app-installations?appIds=f0f86186-0a5a-45b2-aa33-502777496347&searchTerm=string&sortOrder=newestFirst&autoUpdatesActivated=true&autoUpdatesSupported=true&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.app.listAppinstallations({
  "projectId": "string",
  "queryParameters": {
    "appIds": [
      "f0f86186-0a5a-45b2-aa33-502777496347"
    ],
    "searchTerm": "string",
    "sortOrder": "newestFirst",
    "autoUpdatesActivated": true,
    "autoUpdatesSupported": true,
    "limit": 50,
    "page": 1
  }
});

assertStatus(response, 200);
  

use \Mittwald\ApiClient\Generated\V2\Clients\App\ListAppinstallations\ListAppinstallationsRequest;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

$request = (new ListAppinstallationsRequest(
  projectId: "string"
))
  ->withAppIds(["f0f86186-0a5a-45b2-aa33-502777496347"])
  ->withSearchTerm("string")
  ->withSortOrder("newestFirst")
  ->withAutoUpdatesActivated(true)
  ->withAutoUpdatesSupported(true)
  ->withLimit(50)
  ->withPage(1);
$response = $client->app()->listAppinstallations($request);

var_dump($response->getBody();
  

List app installations belonging to a Project

Request​

Path parametersrequired

Query parameters

Responses​

OK200

Too Many Requests429

default

Usage examples​

On this page

Request

Responses

Usage examples