Breaking (!) API changes for v2 API, August 1 to August 8

During the week of August 1 to August 8, 2025, the mittwald API introduced several changes, including the requirement of request bodies for multiple endpoints, modifications to request parameter types, and the addition of new required and optional response properties across various operations.

Breaking changes

This document contains changes that can under certain circumstances be considered breaking. Please review the changes carefully.

While we generally strive to avoid breaking changes in accordance with our API stability guarantees, we occasionally might perform changes that would be considered breaking in the strictest sense of the term, but we do not consider as breaking in a practical sense. We will always provide ample notice and documentation for such changes.

Summary

• The request body has become required for the following operations. They were necessary even before this change, but now that fact is correctly represented in the schema:

  • POST /v2/actions/detect-phishing-email: Check if an email is from mittwald.
  • POST /v2/actions/list-ingresses-compatible-with-certificate: List Ingresses compatible with a certificate.
  • POST /v2/actions/verify-address: Check if an address exists.
  • POST /v2/actions/verify-company: Check if a company exists.
  • POST /v2/certificate-requests: Create a CertificateRequest.
  • PUT /v2/certificates/{certificateId}: Update a Certificate.
  • POST /v2/certificates/{certificateId}/actions/check-replace-certificate: Check the replacement of a Certificate.
  • PATCH /v2/delivery-boxes/{deliveryBoxId}/description: Update the description of a DeliveryBox.
  • PATCH /v2/delivery-boxes/{deliveryBoxId}/password: Update the password of a DeliveryBox.
  • PUT /v2/deliveryboxes/{id}/description: Update the description of a deliverybox.
  • PUT /v2/deliveryboxes/{id}/password: Update the password for a specific deliverybox.
  • POST /v2/dns-zones: Create a DNSZone.
  • PUT /v2/dns-zones/{dnsZoneId}/record-sets/{recordSet}: Update a record set on a DNSZone.
  • POST /v2/dns-zones/{dnsZoneId}/record-sets/{recordSet}/actions/set-managed: Set a record set on a DNSZone to managed.
  • POST /v2/domain-registrable: Check if a Domain is available to register.
  • POST /v2/domain-transferable: Check if a Domain is available to transfer.
  • POST /v2/domains: Check if a Domain is available to register (deprecated).
  • PATCH /v2/domains/{domainId}/auth-code: Update the auth code of a Domain.
  • PATCH /v2/domains/{domainId}/contacts/{contact}: Update a contact of a Domain.
  • PATCH /v2/domains/{domainId}/nameservers: Update the nameservers of a Domain.
  • PATCH /v2/domains/{domainId}/project-id: Update a Domain's project id.
  • PATCH /v2/mail-addresses/{mailAddressId}/address: Update a MailAddress.
  • PATCH /v2/mail-addresses/{mailAddressId}/autoresponder: Update the autoresponder of a MailAddress.
  • PATCH /v2/mail-addresses/{mailAddressId}/catch-all: Update the catch-all of a MailAddress.
  • PATCH /v2/mail-addresses/{mailAddressId}/forward-addresses: Update the forward addresses of a MailAddresses.
  • PATCH /v2/mail-addresses/{mailAddressId}/password: Update the password for a MailAddress.
  • PATCH /v2/mail-addresses/{mailAddressId}/quota: Update the quota of a MailAddress.
  • PATCH /v2/mail-addresses/{mailAddressId}/spam-protection: Update the spam protection of a MailAddress.
  • POST /v2/projects/{projectId}/delivery-boxes: Create a DeliveryBox.
  • PATCH /v2/projects/{projectId}/mail-settings/{mailSetting}: Update a mail setting of a Project.
  • PUT /v2/projects/{projectId}/mail-settings/{setting}: Update a mail setting of a Project (deprecated).
  • PUT /v2/projects/{projectId}/mailsettings/blacklist: Update blacklist for a given project ID (deprecated).
  • PUT /v2/projects/{projectId}/mailsettings/whitelist: Update whitelist for a given project ID (deprecated).

• The type/format of the 'projectId' request parameter has changed from 'string'/'uuid' to 'string'/'' in order to allow the usage of project shortIDs instead of their ID for the following operations:

  • GET /v2/certificate-requests: List CertificateRequests belonging to a Project or an Ingress.
  • GET /v2/certificates: List Certificates belonging to a Project or an Ingress.
  • GET /v2/domains: List Domains.
  • GET /v2/ingresses: List Ingresses.
  • GET /v2/projects/{projectId}/dns-zones: List DNSZones belonging to a Project.
  • GET /v2/projects/{projectId}/domains: List Domains belonging to a Project (deprecated).
  • GET /v2/projects/{projectId}/ingresses: List Ingresses belonging to a project (deprecated).
  • GET /v2/projects/{projectId}/mail-addresses: List MailAddresses belonging to a Project.
  • GET /v2/projects/{projectId}/app-installations: List AppInstallations belonging to a Project.

• The type/format of the 'domainId' request parameter has changed from 'string'/'uuid' to 'string'/'' in order to allow the usage of domain hostnames instead of their ID for the following operations:

  • DELETE /v2/domains/{domainId}: Delete a Domain.
  • GET /v2/domains/{domainId}: Get a Domain.
  • POST /v2/domains/{domainId}/actions/auth-code: Create an auth code for a Domains transfer-out process.
  • POST /v2/domains/{domainId}/actions/resend-email: Resend a Domain email.
  • PATCH /v2/domains/{domainId}/auth-code: Update the auth code of a Domain.
  • PATCH /v2/domains/{domainId}/contacts/{contact}: Update a contact of a Domain.
  • DELETE /v2/domains/{domainId}/declaration: Abort a Domain declaration.
  • PUT /v2/domains/{domainId}/declarations/authcode: Update an AuthCode (deprecated).
  • PUT /v2/domains/{domainId}/declarations/handles: Update a Domain's OwnerC handle (deprecated).
  • PUT /v2/domains/{domainId}/handles/ownerc: Change the owner contact of a domain (deprecated).

• The following response properties have become required for the status '200':

  • /items/linkedDatabases and /items/projectId for GET /v2/app-installations.
  • /items/systemSoftware, /items/updatePolicy, and /items/userInputs for GET /v2/app-installations.
  • /items/supportedFeatures for GET /v2/projects and GET /v2/projects/{projectId}.

• The following optional properties have been added to the response with the '200' status:

  • /items/backendPathTemplate for GET /v2/apps/{appId}/versions, GET /v2/apps/{appId}/versions/{baseAppVersionId}/update-candidates.
  • backendPathTemplate for GET /v2/apps/{appId}/versions/{appVersionId}.

• New optional request parameters have been added:

  • type and type-not for GET /v2/notifications.
  • recreate for PATCH /v2/stacks/{stackId}.
  • skipRecreate for POST /v2/stacks/{stackId}/services/{serviceId}/actions/pull.

• A non-success response with the status '412' has been added for POST /v2/extensions/{extensionId}/order.

Disclaimer: This summary is AI-generated. If you find any discrepancies, please refer to the detailed changes below.

Detailed changes

Changes in "Check if an email is from mittwald"

Changes in "Get a mail address"

• the 'mailbox/storageInBytes/current/value' response's property type/format changed from 'number'/'' to 'number'/'int64' for status '200'

• the 'mailbox/storageInBytes/limit' response's property type/format changed from 'number'/'' to 'number'/'int64' for status '200'

For details, refer to the GET/v2/mail-addresses/{mailAddressId}/ endpoint.

Changes in "Update the quota of a mail address"

• the 'quotaInBytes' request property type/format changed from 'number'/'' to 'number'/'int64'

For details, refer to the PATCH/v2/mail-addresses/{mailAddressId}/quota/ endpoint.

Changes in "Update the quota of a mail address"

• the 'quotaInBytes' request property type/format changed from 'number'/'' to 'number'/'int64'

For details, refer to the PUT/v2/mail-addresses/{mailAddressId}/quota/ endpoint.

Changes in "List mail addresses belonging to a Project"

• the '/items/mailbox/storageInBytes/current/value' response's property type/format changed from 'number'/'' to 'number'/'int64' for status '200'

• the '/items/mailbox/storageInBytes/limit' response's property type/format changed from 'number'/'' to 'number'/'int64' for status '200'

For details, refer to the GET/v2/projects/{projectId}/mail-addresses/ endpoint.

Changes in "Create a mail address"

• the '/oneOf[#/components/schemas/de.mittwald.v1.mail.CreateMailAddress]/mailbox/quotaInBytes' request property type/format changed from 'number'/'' to 'number'/'int64'

For details, refer to the POST/v2/projects/{projectId}/mail-addresses/ endpoint.

Changes in "List app installations that a user has access to"

• the response property '/items/linkedDatabases' became required for the status '200'

• the response property '/items/projectId' became required for the status '200'

• the response property '/items/systemSoftware' became required for the status '200'

• the response property '/items/updatePolicy' became required for the status '200'

• the response property '/items/userInputs' became required for the status '200'

For details, refer to the GET/v2/app-installations/ endpoint.

Changes in "Get an app installation"

• the response property 'linkedDatabases' became required for the status '200'

• the response property 'projectId' became required for the status '200'

• the response property 'systemSoftware' became required for the status '200'

• the response property 'updatePolicy' became required for the status '200'

• the response property 'userInputs' became required for the status '200'

For details, refer to the GET/v2/app-installations/{appInstallationId}/ endpoint.

Changes in "List app versions belonging to an app"

• added the optional property '/items/backendPathTemplate' to the response with the '200' status

For details, refer to the GET/v2/apps/{appId}/versions/ endpoint.

Changes in "Get an app version"

• added the optional property 'backendPathTemplate' to the response with the '200' status

For details, refer to the GET/v2/apps/{appId}/versions/{appVersionId}/ endpoint.

Changes in "List update candidates belonging to an app version"

• added the optional property '/items/backendPathTemplate' to the response with the '200' status

For details, refer to the GET/v2/apps/{appId}/versions/{baseAppVersionId}/update-candidates/ endpoint.

Changes in "Order Extension with saved payment method"

• added the non-success response with the status '412'

For details, refer to the POST/v2/extensions/{extensionId}/order/ endpoint.

Changes in "List all unread notifications"

• added the new optional 'query' request parameter 'type'

• added the new optional 'query' request parameter 'type-not'

For details, refer to the GET/v2/notifications/ endpoint.

Changes in "List Projects belonging to the executing user"

• added the required property '/items/supportedFeatures' to the response with the '200' status

For details, refer to the GET/v2/projects/ endpoint.

Changes in "Get a Project"

• added the required property 'supportedFeatures' to the response with the '200' status

For details, refer to the GET/v2/projects/{projectId}/ endpoint.

Changes in "List app installations belonging to a Project"

• the response property '/items/linkedDatabases' became required for the status '200'

• the response property '/items/projectId' became required for the status '200'

• the response property '/items/systemSoftware' became required for the status '200'

• the response property '/items/updatePolicy' became required for the status '200'

• the response property '/items/userInputs' became required for the status '200'

For details, refer to the GET/v2/projects/{projectId}/app-installations/ endpoint.

Changes in "Create, update or delete Services or Volumes belonging to a Stack"

• added the new optional 'query' request parameter 'recreate'

For details, refer to the PATCH/v2/stacks/{stackId}/ endpoint.

Changes in "Pulls the latest version of the Service's image and optionally recreates the Service"

• added the new optional 'query' request parameter 'skipRecreate'

For details, refer to the POST/v2/stacks/{stackId}/services/{serviceId}/actions/pull/ endpoint.

Client package releases

mittwald JavaScript SDK Release 4.197.0

The mittwald JavaScript SDK has been updated to version 4.197.0. This release includes an update to the generated client, enhancing the SDK's functionality. For more details, you can view the release on GitHub here.

mittwald JavaScript SDK Release 4.196.0

The mittwald JavaScript SDK has been updated to version 4.196.0. This release includes an update to the generated client, enhancing the SDK's functionality. For more details, you can view the release on GitHub here.

mittwald JavaScript SDK Release 4.195.0

The mittwald JavaScript SDK has been updated to version 4.195.0. This release includes an update to the generated client, enhancing the SDK's functionality. For more details, you can view the release on GitHub.

mittwald JavaScript SDK Release 4.194.0

The mittwald JavaScript SDK has been updated to version 4.194.0. This release includes an update to the generated client, enhancing the SDK's functionality. For more details, you can view the release on GitHub.