# mittwald Developer Portal

The mittwald Developer Portal provides comprehensive documentation for the mittwald mStudio v2 API, CLI tools, and cloud platform services. mittwald is a German hosting provider offering managed hosting solutions including projects, servers, databases, containers, domains, email services, and AI hosting capabilities. The platform enables developers to programmatically manage their hosting infrastructure through a RESTful API, command-line interface, and client SDKs for JavaScript, PHP, and Go.

The mStudio v2 API uses `https://api.mittwald.de/v2/` as its base URL and follows OpenAPI 3.0 specifications. Authentication is handled via API tokens passed in `X-Access-Token` or `Authorization: Bearer` headers. The platform supports eventual consistency with `etag` and `if-event-reached` headers for handling read model updates. Rate limiting is enforced with standard headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`).

## API Authentication

Obtain an API token from the mStudio UI or via API, then use it to authenticate all requests.

```bash
# Create a new API token (requires existing token)
curl -X POST https://api.mittwald.de/v2/users/self/api-tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <EXISTING_API_TOKEN>" \
  -d '{
    "description": "My API token",
    "expiresAt": "2025-12-31T23:59:59+00:00",
    "roles": ["api_read", "api_write"]
  }'

# Use token in requests (two methods)
curl -X GET https://api.mittwald.de/v2/user \
  -H "X-Access-Token: <API_TOKEN>"

curl -X GET https://api.mittwald.de/v2/user \
  -H "Authorization: Bearer <API_TOKEN>"
```

## Project Management API

Create and manage projects on servers or as standalone proSpace deployments with dedicated resources.

```bash
# List available servers
curl -X GET https://api.mittwald.de/v2/servers \
  -H "Authorization: Bearer <API_TOKEN>"

# Create a project on an existing server
curl -X POST https://api.mittwald.de/v2/servers/<SERVER_ID>/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "description": "My Web Application"
  }'

# Create a standalone proSpace project (billed separately)
curl -X POST https://api.mittwald.de/v2/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "orderType": "projectHosting",
    "orderData": {
      "customerId": "<CUSTOMER_ID>",
      "description": "Production Website",
      "diskspaceInGiB": 40,
      "spec": {
        "machineType": "shared.medium"
      }
    }
  }'

# Check if project is ready
curl -X GET https://api.mittwald.de/v2/projects/<PROJECT_ID> \
  -H "Authorization: Bearer <API_TOKEN>"
# Response includes "isReady": true when available
```

## Node.js/Python Application Deployment API

Deploy custom Node.js or Python applications that start their own webserver processes.

```bash
# Node.js App ID: 3e7f920b-a711-4d2f-9871-661e1b41a2f0
# Python App ID: be57d166-dae9-4480-bae2-da3f3c6f0a2e

# Get recommended app version for Node.js
curl -X GET "https://api.mittwald.de/v2/apps/3e7f920b-a711-4d2f-9871-661e1b41a2f0/versions?recommended=true" \
  -H "Authorization: Bearer <API_TOKEN>"

# Install Node.js application in a project
curl -X POST https://api.mittwald.de/v2/projects/<PROJECT_ID>/app-installations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "appVersionId": "<APP_VERSION_ID>",
    "description": "My Node.js API",
    "updatePolicy": "none",
    "userInputs": [
      {
        "name": "entrypoint",
        "value": "npm start"
      }
    ]
  }'

# Get installation details including installationPath
curl -X GET https://api.mittwald.de/v2/app-installations/<INSTALLATION_ID> \
  -H "Authorization: Bearer <API_TOKEN>"
```

## Docker Container Management API

Run custom Docker containers with volumes, environment variables, and domain connections.

```bash
# Create a private container registry (optional)
curl -X POST https://api.mittwald.de/v2/projects/<PROJECT_ID>/registries \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "credentials": {
      "password": "registry-password",
      "username": "registry-user"
    },
    "description": "My Private Registry",
    "uri": "my-registry.example.com"
  }'

# List container stacks to find the default stack
curl -X GET https://api.mittwald.de/v2/projects/<PROJECT_ID>/stacks \
  -H "Authorization: Bearer <API_TOKEN>"

# Declare container stack with services and volumes
curl -X PUT https://api.mittwald.de/v2/stacks/<STACK_ID> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "services": {
      "webapp": {
        "image": "nginx:alpine",
        "volumes": ["data:/var/www"],
        "entrypoint": ["/docker-entrypoint.sh"],
        "command": ["nginx", "-g", "daemon off;"],
        "environment": {
          "APP_ENV": "production",
          "LOG_LEVEL": "info"
        }
      }
    },
    "volumes": {
      "data": {}
    }
  }'

# Stop/Start container services
curl -X POST https://api.mittwald.de/v2/stacks/<STACK_ID>/services/<SERVICE_NAME>/actions/stop \
  -H "Authorization: Bearer <API_TOKEN>"

curl -X POST https://api.mittwald.de/v2/stacks/<STACK_ID>/services/<SERVICE_NAME>/actions/start \
  -H "Authorization: Bearer <API_TOKEN>"
```

## DNS Management API

Configure A, AAAA, CNAME, and MX records for domains and subdomains.

```bash
# List DNS zones for a project
curl -X GET "https://api.mittwald.de/v2/projects/<PROJECT_ID>/dns-zones" \
  -H "Authorization: Bearer <API_TOKEN>"

# Set A and AAAA records
curl -X PATCH https://api.mittwald.de/v2/dns-zones/<ZONE_ID>/record-sets/a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "a": ["203.0.113.1", "203.0.113.2"],
    "aaaa": ["2001:0DB8::1", "2001:0DB8::2"],
    "settings": { "ttl": { "auto": true } }
  }'

# Create a subdomain ingress first
curl -X POST https://api.mittwald.de/v2/ingresses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "hostname": "api.example.com",
    "paths": [{ "path": "/", "target": { "useDefaultPage": true } }],
    "projectId": "<PROJECT_ID>"
  }'

# Set CNAME record for subdomain
curl -X PATCH https://api.mittwald.de/v2/dns-zones/<ZONE_ID>/record-sets/cname \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "fqdn": "cdn.cloudprovider.example",
    "settings": { "ttl": { "auto": true } }
  }'

# Reset to platform-managed records
curl -X POST https://api.mittwald.de/v2/dns-zones/<ZONE_ID>/record-sets/a/actions/set-managed \
  -H "Authorization: Bearer <API_TOKEN>"
```

## Email Management API

Create email accounts, forwarding addresses, and delivery boxes for SMTP sending.

```bash
# Create email address with mailbox
curl -X POST https://api.mittwald.de/v2/projects/<PROJECT_ID>/mail-addresses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "address": "contact@example.com",
    "mailbox": {
      "password": "secure-mailbox-password",
      "quotaInBytes": 5368709120
    }
  }'

# Create forwarding address
curl -X POST https://api.mittwald.de/v2/projects/<PROJECT_ID>/mail-addresses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "address": "info@example.com",
    "forwardAddresses": ["contact@example.com", "backup@personal.com"]
  }'

# Create delivery box for application SMTP
curl -X POST https://api.mittwald.de/v2/projects/<PROJECT_ID>/delivery-boxes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "description": "Web Application Mailer",
    "password": "smtp-delivery-password"
  }'

# Delete email address or delivery box
curl -X DELETE https://api.mittwald.de/v2/mail-addresses/<MAIL_ADDRESS_ID> \
  -H "Authorization: Bearer <API_TOKEN>"
```

## CLI Installation and Authentication

Install the mittwald CLI and authenticate for project management.

```bash
# macOS installation via Homebrew
brew tap mittwald/cli
brew install mw
mw --help

# Windows: Download installer from GitHub releases
# https://github.com/mittwald/cli/releases

# NPM installation (any OS with Node.js 18+)
npm install -g @mittwald/cli
mw --help

# Docker usage
export MITTWALD_API_TOKEN=<YOUR_API_TOKEN>
docker run --rm -it -e MITTWALD_API_TOKEN mittwald/cli --help

# Authenticate CLI
mw login

# Enable autocompletion
mw autocomplete
mw autocomplete --refresh-cache  # After CLI updates
```

## CLI Project and Database Commands

Manage projects, databases, backups, and SSH access via CLI.

```bash
# List projects
mw project list

# Create a new project on a server
mw project create --server-id <SERVER_ID> --description "My Project" --wait

# Get project details
mw project get <PROJECT_ID>

# SSH into a project
mw project ssh <PROJECT_ID>

# Create MySQL database
mw database mysql create --description "Production DB" --version 8.0

# Set password via environment (avoids shell history)
read -s MYSQL_PWD && export MYSQL_PWD
mw database mysql create --description "App Database" --version 8.0 \
  --character-set utf8mb4 --collation utf8mb4_unicode_ci

# Backup and restore MySQL
mw database mysql dump <DATABASE_ID> --output backup.sql.gz --gzip
mw database mysql import <DATABASE_ID> --input backup.sql.gz --gzip

# Create project backup
mw backup create --wait --expires 30d

# Download and restore backup
mw backup download <BACKUP_ID> --format tar --output backup.tar.gz
```

## JavaScript SDK

Use the auto-generated TypeScript/JavaScript client for browser and Node.js applications.

```javascript
// Install: npm install @mittwald/api-client

import { MittwaldAPIV2Client } from "@mittwald/api-client";

// Initialize with API token
const client = MittwaldAPIV2Client.newWithToken("<API_TOKEN>");

// List projects
const projects = await client.project.listProjects();
console.log(projects.data);

// Get specific project
const project = await client.project.getProject({
  projectId: "<PROJECT_ID>"
});
console.log(project.data);

// Create a project on a server
const newProject = await client.project.createProject({
  serverId: "<SERVER_ID>",
  data: {
    description: "My New Project"
  }
});
console.log(newProject.data.id);

// React client usage with AsyncResource
import { MittwaldAPIV2ClientReact } from "@mittwald/api-client";

function ProjectList() {
  const projects = MittwaldAPIV2ClientReact.project.listProjects();

  return (
    <ul>
      {projects.data?.map(p => <li key={p.id}>{p.description}</li>)}
    </ul>
  );
}
```

## PHP SDK

Use the Composer-installable PHP client for backend integrations.

```php
<?php
// Install: composer require mittwald/api-client

use Mittwald\ApiClient\MittwaldAPIV2Client;

// Initialize with API token (recommended)
$client = MittwaldAPIV2Client::newWithToken('<API_TOKEN>');

// Or with credentials (no 2FA support)
$client = MittwaldAPIV2Client::newWithCredentials('email@example.com', 'password');

// List all projects
$projects = $client->project()->listProjects();
foreach ($projects as $project) {
    echo $project->getDescription() . "\n";
}

// Get project details
$project = $client->project()->getProject('<PROJECT_ID>');
echo "Project: " . $project->getDescription() . "\n";
echo "Ready: " . ($project->getIsReady() ? 'Yes' : 'No') . "\n";

// Create MySQL database
$database = $client->database()->createMysqlDatabase('<PROJECT_ID>', [
    'description' => 'Application Database',
    'version' => '8.0',
    'password' => 'secure-password'
]);
echo "Database ID: " . $database->getId() . "\n";
```

## Go SDK

Use the Go client library for backend services and automation.

```go
// Install: go get github.com/mittwald/api-client-go

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/mittwald/api-client-go/mittwaldv2"
)

func main() {
    // Initialize with API token
    client, err := mittwaldv2.New(
        mittwaldv2.WithAccessToken("<API_TOKEN>"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Or use environment variable MITTWALD_API_TOKEN
    client, err = mittwaldv2.New(
        mittwaldv2.WithAccessTokenFromEnv(),
    )

    ctx := context.Background()

    // List projects
    projects, err := client.Project.ListProjects(ctx)
    if err != nil {
        log.Fatal(err)
    }

    for _, p := range projects {
        fmt.Printf("Project: %s (%s)\n", p.Description, p.ID)
    }

    // Get specific project
    project, err := client.Project.GetProject(ctx, "<PROJECT_ID>")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Ready: %v\n", project.IsReady)
}
```

## Deployer Integration for PHP

Deploy PHP applications using the mittwald Deployer recipe with automatic SSH setup.

```php
<?php
// Install: composer require --dev mittwald/deployer-recipes

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/vendor/mittwald/deployer-recipes/recipes/deploy.php';

// Simple deployment configuration
mittwald_app('<APP_ID>')
    ->set('public_path', '/public');

// Multiple environments
mittwald_app('<PROD_APP_ID>', hostname: 'mittwald-prod')
    ->set('branch', 'main');

mittwald_app('<STAGING_APP_ID>', hostname: 'mittwald-staging')
    ->set('branch', 'develop');

// Configure PHP version and dependencies
set('mittwald_app_dependencies', [
    'php' => '~8.2',
    'composer' => '>=2.0',
]);

// Configure domains
set('mittwald_domains', ['example.com', 'www.example.com']);
```

```bash
# Deploy with API token
export MITTWALD_API_TOKEN=<YOUR_TOKEN>
./vendor/bin/dep deploy

# Deploy specific environment
./vendor/bin/dep deploy mittwald-prod
```

## AI Hosting API (OpenAI-Compatible)

Access LLM models, embeddings, and audio transcription via OpenAI-compatible endpoints.

```bash
export APIKEY=sk-...

# List available models
curl -X GET https://llm.aihosting.mittwald.de/v1/models \
    -H "Authorization: Bearer $APIKEY"

# Chat completion
curl -X POST https://llm.aihosting.mittwald.de/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $APIKEY" \
    -d '{
        "model": "Ministral-3-14B-Instruct-2512",
        "messages": [{"role": "user", "content": "Explain Docker containers briefly"}],
        "temperature": 0.15
    }'

# Streaming response
curl -N -X POST https://llm.aihosting.mittwald.de/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $APIKEY" \
    -d '{
        "model": "Ministral-3-14B-Instruct-2512",
        "messages": [{"role": "user", "content": "Write a haiku about APIs"}],
        "stream": true,
        "temperature": 0.15,
        "top_k": 10,
        "top_p": 0.5
    }'

# Vision (image analysis)
curl -X POST https://llm.aihosting.mittwald.de/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $APIKEY" \
    -d '{
        "model": "Ministral-3-14B-Instruct-2512",
        "messages": [{
          "role": "user",
          "content": [
            {"type": "text", "text": "What is in this image?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
          ]
        }],
        "temperature": 0.1
    }'

# Generate embeddings
curl -X POST https://llm.aihosting.mittwald.de/v1/embeddings \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $APIKEY" \
    -d '{
        "model": "Qwen3-Embedding-8B",
        "input": "Document to embed for semantic search"
    }'

# Audio transcription
curl -X POST https://llm.aihosting.mittwald.de/v1/audio/transcriptions \
    -H "Authorization: Bearer $APIKEY" \
    -F "file=@recording.mp3" \
    -F "model=Whisper-Large-V3-Turbo" \
    -F "language=en"
```

## AI Hosting with Python

Use the OpenAI Python library as a drop-in replacement for mittwald AI hosting.

```python
# Install: pip install python-dotenv openai langchain-openai
# Create .env: echo 'OPENAI_API_KEY="sk-..."' > .env

from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(base_url="https://llm.aihosting.mittwald.de/v1")

# Basic chat completion
response = client.chat.completions.create(
    model="Ministral-3-14B-Instruct-2512",
    temperature=0.15,
    messages=[{"role": "user", "content": "Explain Kubernetes in simple terms"}]
)
print(response.choices[0].message.content)

# Streaming responses
stream = client.chat.completions.create(
    model="Devstral-Small-2-24B-Instruct-2512",
    messages=[{"role": "user", "content": "Write a short poem about coding"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

# Tool/function calling
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
        }
    }
}]

resp = client.chat.completions.create(
    model="Devstral-Small-2-24B-Instruct-2512",
    messages=[{"role": "user", "content": "What is the weather in Berlin?"}],
    tools=tools,
    tool_choice="auto"
)

if resp.choices[0].message.tool_calls:
    call = resp.choices[0].message.tool_calls[0]
    print(f"Call function: {call.function.name}({call.function.arguments})")

# Using LangChain
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

chat = ChatOpenAI(
    model="Ministral-3-14B-Instruct-2512",
    base_url="https://llm.aihosting.mittwald.de/v1",
    temperature=0.15
)
response = chat.invoke([HumanMessage(content="Summarize REST API best practices")])
print(response.content)
```

## Summary

The mittwald Developer Portal serves developers building applications on the mittwald cloud platform, providing complete infrastructure automation through REST APIs, CLI tools, and language-specific SDKs. Primary use cases include automated project provisioning, CI/CD pipeline integration using Deployer or custom scripts, database lifecycle management, container orchestration, DNS configuration, and email infrastructure setup. The platform's event-sourced architecture requires handling eventual consistency in automation workflows using the etag/if-event-reached header pattern.

Integration patterns center around the OpenAPI 3.0 specification at `https://api.mittwald.de/openapi`, enabling code generation for any language. The SDKs for JavaScript, PHP, and Go provide type-safe clients with authentication helpers. For AI workloads, the OpenAI-compatible API at `https://llm.aihosting.mittwald.de/v1` allows drop-in replacement in existing applications using standard libraries. The CLI supports both interactive use and non-interactive scripting with `--quiet` and `--output json` flags for machine-readable output in automation pipelines.