API docs by Redocly

lima-city API (1.0.0-oas3)

Download OpenAPI specification:

E-mail: support@lima-city.de License: Apache 2.0

Manage you hosting and services from a simple and effective API.

Please see the "General API FAQ" for information on authentication. In one sentence: use "HTTP Basic Authentication" for authentication, with "api" as the username and your secret API key as the password. That's it.

api_keys

Manage API keys and their role-based permissions. API keys use HTTP Basic Authentication with username api and the generated key as password.

List API keys

List all API keys for the authenticated user. API keys authenticate requests with HTTP Basic Authentication using username api and the key value as password.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/api_keys' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "api_keys": [
    ]
}

Create API key

Create a new API key with one or more role-based permissions. At least one role is required.

Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required
required
object
name
string or null
roles
required
Array of strings non-empty

Role names from GET /api_keys/roles.

Responses

Request samples

Content type
application/json
{
  • "api_key": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

List API key roles

List all role names that can be assigned to API keys.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/api_keys/roles' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "roles": [
    ]
}

Show API key

Show one API key owned by the authenticated user.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

API key ID

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/api_keys/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "api_key": {
    }
}

Update API key

Replace API key name and role assignment.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

API key ID

Request Body schema: application/json
required
required
object
name
string or null
roles
required
Array of strings non-empty

Role names from GET /api_keys/roles.

Responses

Request samples

Content type
application/json
{
  • "api_key": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update API key

Update API key name and role assignment.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

API key ID

Request Body schema: application/json
required
required
object
name
string or null
roles
required
Array of strings non-empty

Role names from GET /api_keys/roles.

Responses

Request samples

Content type
application/json
{
  • "api_key": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Delete API key

Delete an API key owned by the authenticated user.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

API key ID

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/api_keys/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

affiliate_payouts

Request and manage payouts of confirmed affiliate commissions. Affiliates can withdraw their earnings via account balance transfers (minimum 1 EUR) or SEPA bank transfers (minimum 10 EUR). This API supports recurring payout requests and provides payout history with tracking codes.

List affiliate payouts

Retrieve a paginated list of your requested affiliate payouts.

Payout Information: Each payout requests withdrawal of confirmed commissions. Payouts can be sent via:

  • account: Transfer to your lima-city account balance (minimum 1 EUR, added as transaction)
  • sepa: SEPA bank transfer to provided IBAN (minimum 10 EUR)

Each payout receives a unique code for reference in transfer documentation.

Payout Status: Payouts are created when requested and records persist with their destination and amount. Actual payment processing depends on the destination method.

Response: Returns list ordered by newest first, paginated (25 per page).

Authorization: Requires valid user authentication and accepted affiliate ToS.

Authorizations:
apiKeyBasicAuth
query Parameters
page
integer
Example: page=1

Page number for pagination (1-indexed). Defaults to 1. Each page contains up to 25 payouts.

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/affiliate_payouts?page=1' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "payouts": [
    ],
  • "pagination": {
    }
}

Request an affiliate payout

Create and request a new payout of your confirmed affiliate commissions.

Payout Requirements:

For account transfers (destination: 'account'):

  • Minimum amount: 1.00 EUR
  • Funds added as transaction to lima-city account balance
  • No additional recipient info needed

For SEPA transfers (destination: 'sepa'):

  • Minimum amount: 10.00 EUR
  • Requires valid IBAN in international format
  • Requires account holder name (4+ characters, SEPA-compliant only)
  • SEPA CT (Credit Transfer) is initiated
  • Processing time typically 1-3 business days

Amount Constraints:

  • Cannot exceed (confirmed_commissions - already_paid_out)
  • Decimal amounts accepted with comma or period separator
  • Automatically rounded down to 2 decimal places
  • Must be positive

Validation Rules:

  • amount: Required, decimal value. Account min 1.00, SEPA min 10.00
  • destination: Required, either 'account' or 'sepa'
  • iban: Required if destination is 'sepa', must be valid international IBAN
  • account_holder: Required if destination is 'sepa', 4+ characters, no special chars/umlauts

Error Messages (German):

  • "Validierungsfehler" (Validation error) - Typically validation rule violation
  • "Amount too low for SEPA" (German: about min 10 EUR) - Amount below 10 EUR for SEPA
  • "IBAN ist keine gültige IBAN" (IBAN is not a valid IBAN) - Invalid IBAN format
  • "Account holder has invalid characters" - Contains non-SEPA characters or too short

Concurrency Control: Only one payout request can be processed per user at a time (60-second mutual exclusion lock).

Response: Returns status 'ok' on successful creation. Payout record is immediately persisted.

Authorization: Requires valid user authentication and accepted affiliate ToS.

Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required
required
object

Nested affiliate_payout object matching params.require(:affiliate_payout)

amount
required
string

Payout amount to request. For 'account' destination: minimum 1.00 EUR. For 'sepa' destination: minimum 10.00 EUR. Can be provided with comma or period as decimal separator and will be rounded down to 2 decimal places. Must not exceed available confirmed commissions minus previously paid out amounts.

destination
required
string
Enum: "account" "sepa"

Payout destination. 'account' transfers to lima-city user account balance (no minimum). 'sepa' performs SEPA credit transfer (minimum 10 EUR).

iban
string

IBAN for the recipient bank account. Required if destination is 'sepa'. Must be a valid IBAN. Alphanumeric characters are preserved, all special characters are removed.

account_holder
string

Full name of account holder. Required if destination is 'sepa'. Must be 4+ characters with valid SEPA characters only (no umlauts or extended characters). Allowed: letters, digits, space, apostrophe, colon, question mark, comma, hyphen, parentheses, plus, period, slash.

Responses

Request samples

Content type
application/json
{
  • "affiliate_payout": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

commissions

Track affiliate commissions earned from customer referrals and manage the affiliate program. Earn 10% commission on referred customer invoices that are paid. Monitor commission status through their lifecycle (created, confirmed, rejected) and access marketing materials for promotion.

List affiliate commissions

Retrieve a paginated list of affiliate commissions earned through customer referrals.

Commission System Overview: When you refer customers to lima-city using your affiliate link, you earn a 10% commission on their invoices. Commissions go through these states:

  • created: Just created, pending confirmation (appears immediately when referred customer's invoice is created)
  • confirmed: Invoice was paid and 30 days have passed - commission is now available for payout
  • rejected: Invoice was reversed/cancelled - commission is no longer valid

This endpoint returns commissions in both open (uncconfirmed) and confirmed states. Confirmed commissions can be requested for payout.

Affiliate ToS Requirement: You must have accepted the affiliate terms of service to access this endpoint. If not accepted, use the POST accept_tos endpoint first.

Response Structure:

  • new_commissions: Commissions in 'created' state (pending confirmation)
  • commissions: All commissions (paginated) in all states, newest first
  • pagination: Standard pagination metadata

Authorization: Requires valid user authentication and accepted affiliate ToS.

Authorizations:
apiKeyBasicAuth
query Parameters
page
integer
Example: page=1

Page number for pagination (1-indexed). Defaults to 1. Each page contains up to 25 commissions.

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/commissions?page=1' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "commissions": [
    ],
  • "pagination": {
    }
}

Get affiliate marketing media

Retrieve promotional materials and marketing media for affiliate program (banners, links, assets).

Authorization: Requires valid user authentication and accepted affiliate ToS.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/commissions/media' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{ }

Get affiliate promotion information

Retrieve current promotion information and partner details for affiliate program.

Authorization: Requires valid user authentication and accepted affiliate ToS.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/commissions/promotions' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{ }

Accept affiliate terms of service

Accept the affiliate program terms of service to enable access to affiliate commissions and payouts.

Requirements: Accepting the ToS is required before you can:

  • View commissions
  • Request payouts
  • Access affiliate marketing materials
  • Participate in the affiliate program

Once accepted, you can immediately start earning commissions on referred customer invoices.

Authorization: Requires valid user authentication.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/commissions/accept_tos' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "success": true
}

cronjobs

Manage scheduled background tasks for hosted services. Create, monitor, and modify cron jobs for automated tasks like backups, maintenance routines, and periodic data processing on your web space.

List cronjobs

List all scheduled cronjobs for the authenticated user. Returns an array of all configured cron jobs including their schedule, type, and status.

Authorization Requirements:

  • User must have shared hosting access
  • User must have a premium subscription (or higher)

Cronjob Limits:

  • Maximum 100 cronjobs per account
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/cronjobs' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "cronjobs": [
    ]
}

Create cronjob

Create a new scheduled cronjob. Cronjobs can execute shell commands or call HTTP/HTTPS URLs at specified intervals.

Authorization Requirements:

  • User must have shared hosting access
  • User must have a premium subscription (or higher)

Cronjob Types:

  • url: Calls an HTTP/HTTPS URL at scheduled times
  • shell: Executes a shell command at scheduled times

Validation Rules:

  • cronjob_type: Required, must be either 'url' or 'shell'
  • command_or_url: Required, must be a valid HTTP/HTTPS URL if type is 'url'
  • exec_times: Required, must be a valid cron expression (5 fields: minute hour day month weekday)
  • description: Optional, free text description

Cron Expression Format: Standard cron format with 5 fields:

  • Minute (0-59)
  • Hour (0-23)
  • Day of month (1-31)
  • Month (1-12)
  • Day of week (0-6, where 0 is Sunday)

Examples:

  • 0 2 * * * - Every day at 2:00 AM
  • */15 * * * * - Every 15 minutes
  • 0 0 * * 0 - Every Sunday at midnight

Limits:

  • Maximum 100 cronjobs per account
  • Returns 403 error if limit is reached

Error Messages:

  • command_or_url: "muss eine HTTP oder HTTPS-URL sein" (must be an HTTP or HTTPS URL) - when URL type cronjob has invalid URL
  • command_or_url: "ist keine gültige URL" (is not a valid URL) - when URL cannot be parsed
  • exec_times: "Ungültiges Zeitformat: [error details]" (Invalid time format) - when cron expression is invalid
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

Cronjob creation parameters

required
object

Cronjob creation parameters

cronjob_type
required
string
Enum: "url" "shell"

Type of cronjob to create. 'url' for HTTP/HTTPS URL calls, 'shell' for shell command execution

command_or_url
required
string

The command or URL to execute. Must be a valid HTTP/HTTPS URL if cronjob_type is 'url'

exec_times
required
string

Cron schedule expression. Standard cron format with 5 fields: minute (0-59) hour (0-23) day (1-31) month (1-12) weekday (0-6). Must be a valid cron expression

description
string

Optional description of what this cronjob does

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

Show cronjob details

Show details of a specific cronjob including its configuration and recent execution history.

The response includes:

  • Complete cronjob configuration (schedule, type, command/URL)
  • Paginated list of recent executions (cronjob_runs) ordered by most recent first
  • Execution details including start time, duration, response codes, and logs

Authorization Requirements:

  • User must have shared hosting access
  • User must have a premium subscription (or higher)
  • User must own the cronjob
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the cronjob to retrieve

query Parameters
page
integer >= 1
Default: 1

Page number for pagination of cronjob runs (default: 1)

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/cronjobs/12345?page=1' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "cronjob": {
    },
  • "cronjob_runs": [
    ],
  • "pagination": {
    }
}

Update cronjob

Update an existing cronjob's configuration. Can modify the schedule, type, command/URL, or description.

Authorization Requirements:

  • User must have shared hosting access
  • User must have a premium subscription (or higher)
  • User must own the cronjob

Validation Rules:

  • cronjob_type: Must be either 'url' or 'shell' if provided
  • command_or_url: Must be a valid HTTP/HTTPS URL if type is 'url'
  • exec_times: Must be a valid cron expression if provided

Error Messages:

  • command_or_url: "muss eine HTTP oder HTTPS-URL sein" (must be an HTTP or HTTPS URL) - when URL type cronjob has invalid URL
  • command_or_url: "ist keine gültige URL" (is not a valid URL) - when URL cannot be parsed
  • exec_times: "Ungültiges Zeitformat: [error details]" (Invalid time format) - when cron expression is invalid
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the cronjob to update

Request Body schema: application/json
required

Cronjob update parameters

required
object

Cronjob update parameters

cronjob_type
string
Enum: "url" "shell"

Type of cronjob. 'url' for HTTP/HTTPS URL calls, 'shell' for shell command execution

command_or_url
string

The command or URL to execute. Must be a valid HTTP/HTTPS URL if cronjob_type is 'url'

exec_times
string

Cron schedule expression. Standard cron format with 5 fields: minute (0-59) hour (0-23) day (1-31) month (1-12) weekday (0-6). Must be a valid cron expression

description
string

Optional description of what this cronjob does

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Delete cronjob

Permanently delete a cronjob. The cronjob will no longer be executed and all associated execution history will be removed.

Authorization Requirements:

  • User must have shared hosting access
  • User must have a premium subscription (or higher)
  • User must own the cronjob

Warning: This action is permanent and cannot be undone. All execution history (cronjob_runs) will also be deleted.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the cronjob to delete

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/cronjobs/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "success": true
}

Show cronjob run log

Retrieve the full execution log for a specific cronjob run. Returns the complete output/status log from when the cronjob was executed.

Authorization Requirements:

  • User must have shared hosting access
  • User must have a premium subscription (or higher)
  • User must own the cronjob

Response Format:

  • Returns plain text (text/plain) containing the full execution log
  • For URL cronjobs: Contains the HTTP response body
  • For shell cronjobs: Contains the command output/error messages
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the cronjob

run_id
required
integer
Example: 54321

Unique identifier of the specific cronjob run to retrieve

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/cronjobs/12345/runs/54321' \
  --user 'api:YOUR_API_KEY'

database_backups

Create, list, restore, and download backups of your MySQL and PostgreSQL databases. Automated backup scheduling and point-in-time recovery capabilities with download support for archival and migration purposes.

List database backups

List all automatic database backups for the authenticated user with pagination support.

Important Notes:

  • Only backups with ID > 19360 are included (legacy backups excluded)
  • Backups are automatically created by the system
  • Backups older than 90 days are automatically marked as 'deleted'
  • Backups older than 1 year are permanently removed
  • Includes count of currently running restore operations

Requirements:

  • User must have shared hosting access
  • User must have premium subscription (402 error if not premium)

Data Retention:

  • Complete backups are kept for 90 days
  • After 90 days, backups are marked as 'deleted' but metadata retained
  • After 1 year, all backup records are permanently deleted
Authorizations:
apiKeyBasicAuth
query Parameters
page
integer >= 1
Default: 1

Page number for pagination (default: 1)

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/database_backups?page=1' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "database_backups": [
    ],
  • "restore_count": 0,
  • "pagination": {
    }
}

Show database backup

Show details of a specific database backup including download URL and metadata.

Important Notes:

  • Only backups with ID > 19360 can be accessed (legacy backups excluded)
  • Backup must belong to the authenticated user

Requirements:

  • User must have shared hosting access
  • User must have premium subscription (402 error if not premium)
  • User must own the backup
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 54321

Unique identifier of the database backup

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/database_backups/54321' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "id": 54321,
  • "user_id": 9876,
  • "database_name": "db_9876_myapp",
  • "database_id": 12345,
  • "state": "complete",
  • "started_at": "2025-10-20T02:15:00Z",
  • "completed_at": "2025-10-20T02:18:30Z",
  • "finished_at": "2025-10-20T02:18:30Z",
  • "filesize": 1048576,
  • "storage_filename": "backup_20251020_021500_db_9876_myapp.sql.gz",
  • "created_at": "2025-10-20T02:15:00Z",
  • "updated_at": "2025-10-20T02:18:30Z",
  • "password": "string",
  • "job_id": "string",
  • "download_url": "https://restore-api.trafficplex.de/restore-download/restore_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4.zip",
  • "auto_backup": true,
  • "successful": true
}

Download database backup

Initiate a download of a database backup as a compressed archive. This creates a restore request in waiting state and queues a background job to create the downloadable archive.

Process Flow:

  1. Creates a RestoreRequest with unique restore_id
  2. Queues a background job to create the archive
  3. Returns the restore tracking URL in the response body
  4. Poll GET /restores/{restore_id} until state is success
  5. Download the ZIP from restore.target.download_url while restore.target.downloadable is true

Important Notes:

  • This is an asynchronous operation
  • Download URL becomes available when state changes to success
  • Downloads are available for 5 days after completion

Requirements:

  • User must have shared hosting access
  • User must have premium subscription (402 error if not premium)
  • User must own the backup
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 54321

Unique identifier of the database backup to download

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/database_backups/54321/download' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "restore_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  • "url": "/usercp/restores/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

Restore database backup

Restore a database backup to an existing operational database. This overwrites the target database with the backup data.

Process Flow:

  • Validates that target_database_name is an operational database owned by the user
  • Starts the restore process
  • Returns restore_id for tracking progress

Important Notes:

  • THIS WILL OVERWRITE ALL DATA IN THE TARGET DATABASE
  • Confirmation must be explicitly set to true
  • Target database must be in 'operational' state

Validation Rules:

  • target_database_name: Required, must be an operational database owned by user
  • confirmation: Required, must be true (acceptance validation)

Error Messages:

  • "ist keine aktive Datenbank" (is not an active database) - Target database not found or not operational
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 54321

Unique identifier of the database backup to restore

Request Body schema: application/json
required

Restore parameters

required
object

Nested restore parameters matching controller params.require(:restore)

target_database_name
required
string

Name of the target database to restore into. Must be an operational database owned by the user. Format: 'db_USERID_NAME'

confirmation
required
boolean

Must be true to confirm the restore operation (will overwrite existing database content)

Responses

Request samples

Content type
application/json
{
  • "restore": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

database_users

Create and manage database user accounts with granular access permissions. Support for both simple (full database access) and complex (specific tables/operations) permission models. Password management and access control for MySQL and PostgreSQL databases.

List database users

List all database users (MySQL users) with their access permissions.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/database_users' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
[
  • {
    }
]

Create database user

Create a new database user (MySQL user) with specified access permissions to databases.

Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

Database user creation parameters

suffix
required
string

Username suffix (combined with USER_ID to form username)

hostname
required
string
Enum: "localhost" "%"

Hostname restriction for the user

password
required
string <password>

MySQL password (must be secure, cannot contain username or user ID)

access
required
string
Enum: "simple" "complex"

Access mode - 'simple' for predefined access levels or 'complex' for database-specific grants

simple_access
string
Enum: "admin" "readonly" "readwrite" "usage"

Access level when using simple mode (required if access='simple')

Array of objects

Array of database grants (required if access='complex')

Array
required
object
privileges
required
Array of strings
Items Enum: "Select" "Insert" "Update" "Delete" "Create" "Drop" "Grant" "Index" "Alter" "Create_tmp_table" "Lock_tables" "Execute" "Create_view" "Show_view" "Create_routine" "Alter_routine" "Trigger"

List of SQL privileges to grant

comment
string or null

Optional comment for the database user

Responses

Request samples

Content type
application/json
{
  • "suffix": "app",
  • "hostname": "localhost",
  • "password": "pa$$word",
  • "access": "simple",
  • "simple_access": "admin",
  • "grants": [
    ],
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "id": 54321
}

Show database user

Show details of a specific database user including username, access type, and permissions.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the database user to retrieve

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/database_users/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "id": 54321,
  • "username": "USER9876",
  • "host": "localhost",
  • "simple_access": "admin",
  • "comment": "string"
}

Update database user

Update database user access permissions and hostname.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the database user to update

Request Body schema: application/json
required

Database user update parameters

hostname
required
string
Enum: "localhost" "%"

Hostname restriction for the user

access
required
string
Enum: "simple" "complex"

Access mode

simple_access
string
Enum: "admin" "readonly" "readwrite" "usage"

Access level when using simple mode (required if access='simple')

Array of objects

Array of database grants (required if access='complex')

Array
required
object
privileges
required
Array of strings
Items Enum: "Select" "Insert" "Update" "Delete" "Create" "Drop" "Grant" "Index" "Alter" "Create_tmp_table" "Lock_tables" "Execute" "Create_view" "Show_view" "Create_routine" "Alter_routine" "Trigger"

Responses

Request samples

Content type
application/json
{
  • "hostname": "localhost",
  • "access": "simple",
  • "simple_access": "admin",
  • "grants": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Delete database user

Delete a database user (MySQL user). This removes all permissions and the user from the MySQL server.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the database user to delete

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/database_users/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update database user password

Update the password for a database user. Password must not contain username or user ID and must be different from login password.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the database user

Request Body schema: application/json
required

New password

password
required
string <password>

New password (must be secure, cannot contain username or user ID)

Responses

Request samples

Content type
application/json
{
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Show database user grants

Show all database grants (permissions) for a database user including the databases and specific privileges.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the database user

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/database_users/12345/grants' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "id": 54321,
  • "username": "USER9876",
  • "host": "localhost",
  • "simple_access": "admin",
  • "comment": "string",
  • "grants": [
    ]
}

databases

Create, manage, and monitor MySQL and PostgreSQL databases. Full lifecycle management including creation, deletion, sizing, and performance monitoring with integrated user and backup management.

List databases

List all MySQL databases for the authenticated user with pagination support and usage information.

Authorizations:
apiKeyBasicAuth
query Parameters
page
integer >= 1
Default: 1

Page number for pagination (default: 1)

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/databases?page=1' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "databases": [
    ],
  • "pagination": {
    }
}

Create database

Create a new MySQL database. Optionally creates a database user with specified permissions at the same time.

Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

Database creation parameters

collation
string

Character set collation (optional, defaults to utf8mb4_general_ci)

comment
string

Optional comment for the database (max 128 characters)

create_user
boolean

Whether to create a database user at the same time

object

Database user parameters (required if create_user is true)

suffix
string

Username suffix (combined with USER_ID to form username, max 16 chars total)

hostname
string
Enum: "localhost" "%"

Hostname restriction for the user

password
string <password>

Password for the database user

simple_access
string
Enum: "admin" "readonly" "readwrite"

Simple access level for the user

Responses

Request samples

Content type
application/json
{
  • "collation": "utf8mb4_general_ci",
  • "comment": "Production database",
  • "create_user": false,
  • "database_user": {
    }
}

Response samples

Content type
application/json
{
  • "id": 12345
}

Show database

Show details of a specific MySQL database including name, state, collation, and comment.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the database to retrieve

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/databases/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "db_9876_myapp",
  • "state": "operational",
  • "created": 1532363041,
  • "collation": "utf8mb4_general_ci",
  • "comment": "Production database",
  • "access_disabled_at": "2019-08-24T14:15:22Z"
}

Update database

Update database settings (currently only comment field can be updated).

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the database to update

Request Body schema: application/json
required

Database update parameters

comment
required
string

Updated comment for the database (max 128 characters)

Responses

Request samples

Content type
application/json
{
  • "comment": "Updated production database"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Delete database

Delete a MySQL database. The database must be in operational state to be deleted.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the database to delete

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/databases/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Purge database

Delete all data from a MySQL database while keeping the database structure and users intact.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the database to purge

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/databases/12345/purge' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Get database usage

Get usage statistics for all databases including storage information.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/databases/usage' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "total_usage": "156 MB",
  • "databases": [
    ]
}

ftp_accounts

Create and manage FTP and SFTP user accounts for secure file transfer. Set directory restrictions, manage permissions, and control access to your web space with support for password authentication and modern SFTP protocols.

List FTP accounts

List all FTP accounts for the authenticated user.

FTP accounts provide FTP/FTPS access to the user's webspace. Each account has an auto-generated username and can be restricted to a specific directory within the user's home directory.

Account Limits:

  • Free accounts: Maximum 10 FTP accounts
  • Premium accounts: Maximum 1000 FTP accounts

Validation Error: If limit is reached: 'Du kannst maximal X FTP-Accounts erstellen (Freespace-Account)' or '(Premium-Account)' (You can create a maximum of X FTP accounts)

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/ftp_accounts' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "ftp_accounts": [
    ]
}

Create FTP account

Create a new FTP account with an auto-generated username.

The username is automatically generated in the format 'ftp_XXXXXXXX' where X is a random lowercase alphanumeric character.

Password Requirements:

  • Minimum 8 characters
  • Alphanumeric only, plus hyphens (-) and underscores (_)
  • No special characters allowed
  • Must not contain the user's login username
  • Must not be the same as the user's login password

Directory Validation:

  • Must be within the user's home directory
  • Can be the home directory itself
  • Validated using PathCheck to ensure no directory traversal

Account Limits:

  • Free accounts: Maximum 10 FTP accounts
  • Premium accounts: Maximum 1000 FTP accounts

Validation Rules:

  • password: Required, minimum 8 characters
  • directory: Optional, must be within home directory
  • comment: Optional, maximum 250 characters

Error Messages:

  • 'darf Deinen Benutzernamen nicht enthalten' (password must not contain your username)
  • 'darf nicht gleich Deinem Login-Passwort sein' (password must not equal your login password)
  • 'darf keine Sonderzeichen (X Y Z) enthalten' (password must not contain special characters X Y Z)
  • 'liegt nicht im Benutzerverzeichnis' (directory is not within user directory)
  • 'Du kannst maximal X FTP-Accounts erstellen (Freespace-Account)' or '(Premium-Account)' (You can create a maximum of X FTP accounts)
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

FTP account creation parameters

required
object

FTP account creation parameters matching controller params.require(:ftp_account)

password
required
string <password> >= 8 characters

Password for the FTP account. Must be at least 8 characters, alphanumeric with hyphens and underscores only (no special characters). Cannot contain the user's login username or login password. Validation errors: 'darf Deinen Benutzernamen nicht enthalten' (must not contain your username), 'darf nicht gleich Deinem Login-Passwort sein' (must not equal your login password), 'darf keine Sonderzeichen enthalten' (must not contain special characters)

directory
string or null

Root directory for FTP access, relative to home directory. Must be within user's home directory or the home directory itself. If omitted, defaults to home directory. Validation error: 'liegt nicht im Benutzerverzeichnis' (not within user directory)

comment
string or null <= 250 characters

Optional comment/description (max 250 characters)

Responses

Request samples

Content type
application/json
{
  • "ftp_account": {
    }
}

Response samples

Content type
application/json
{
  • "id": 12345
}

Show FTP account

Show details of a specific FTP account including username, directory, comment, TLS settings, and timestamps.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the FTP account to retrieve

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/ftp_accounts/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "id": 12345,
  • "username": "ftp_abc12def",
  • "directory": "/html",
  • "comment": "Main website FTP access",
  • "force_tls": 1,
  • "created_at": "2025-10-15T10:30:00Z",
  • "updated_at": "2025-10-15T10:30:00Z"
}

Delete FTP account

Delete an FTP account permanently. This action cannot be undone.

Warning: This will immediately revoke FTP access for this account. Any active FTP sessions using this account will be terminated.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the FTP account to delete

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/ftp_accounts/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update FTP account password

Update the password for an FTP account.

Password Requirements:

  • Minimum 8 characters
  • Alphanumeric only, plus hyphens (-) and underscores (_)
  • No special characters allowed
  • Must not contain the user's login username
  • Must not be the same as the user's login password

Validation Rules:

  • password: Required, minimum 8 characters

Error Messages:

  • 'darf Deinen Benutzernamen nicht enthalten' (password must not contain your username)
  • 'darf nicht gleich Deinem Login-Passwort sein' (password must not equal your login password)
  • 'darf keine Sonderzeichen (X Y Z) enthalten' (password must not contain special characters X Y Z)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the FTP account to update

Request Body schema: application/json
required

Password update parameters

required
object
password
required
string <password> >= 8 characters

New password for the FTP account. Must be at least 8 characters, alphanumeric with hyphens and underscores only. Cannot contain the user's login username or login password

Responses

Request samples

Content type
application/json
{
  • "ftp_account": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update FTP account directory

Update the root directory for an FTP account.

The directory path is relative to the user's home directory and restricts FTP access to that directory and its subdirectories.

Directory Validation:

  • Must be within the user's home directory
  • Can be the home directory itself
  • Validated using PathCheck to ensure no directory traversal
  • Path is normalized and cleaned before validation

Validation Rules:

  • directory: Required, must be within home directory

Error Messages:

  • 'liegt nicht im Benutzerverzeichnis' (directory is not within user directory)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the FTP account to update

Request Body schema: application/json
required

Directory update parameters

required
object
directory
required
string

New root directory for FTP access, relative to home directory. Must be within user's home directory or the home directory itself

Responses

Request samples

Content type
application/json
{
  • "ftp_account": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update FTP account comment

Update the comment/description for an FTP account.

Validation Rules:

  • comment: Required, maximum 250 characters
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the FTP account to update

Request Body schema: application/json
required

Comment update parameters

required
object
comment
required
string or null <= 250 characters

New comment/description (max 250 characters)

Responses

Request samples

Content type
application/json
{
  • "ftp_account": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update FTP account TLS requirement

Update whether TLS encryption is required for this FTP account.

TLS Settings:

  • When enabled (true): Only FTPS connections are allowed (explicit FTP over TLS)
  • When disabled (false): Both plain FTP and FTPS connections are allowed

Security Recommendation: It is strongly recommended to keep TLS required (enabled) for security. Plain FTP transmits credentials and data unencrypted.

Validation Rules:

  • force_tls: Required, boolean value
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the FTP account to update

Request Body schema: application/json
required

TLS requirement update parameters

required
object
force_tls
required
boolean

Whether to require TLS encryption. true = TLS required (FTPS only), false = TLS optional (allows plain FTP)

Responses

Request samples

Content type
application/json
{
  • "ftp_account": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Download FileZilla configuration

Download a pre-configured FileZilla XML configuration file for this FTP account.

This endpoint returns an XML file that can be imported into FileZilla FTP client to automatically configure connection settings including hostname, username, and directory. The password is not included in the configuration file.

File Format: XML file with Content-Disposition header set to 'attachment; filename=FileZilla_lima-city_{username}.xml'

TLS Configuration: The configuration will set up FileZilla to use explicit FTP over TLS (FTPS) for secure connections.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the FTP account

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/ftp_accounts/12345/filezilla_config.xml' \
  --user 'api:YOUR_API_KEY'

handles

Manage domain and SSL certificate registrations. Actions include ordering new handles, checking availability, renewing registrations, and managing handle configurations and contact information.

List contact handles

List all contact handles (WHOIS contacts) for the authenticated user. Returns only non-deleted handles.

Handles are used for domain registration, transfers, and billing purposes. They contain personal or organizational contact information that appears in WHOIS records.

Authorization Requirements:

  • User must be authenticated
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/handles' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "handles": [
    ]
}

Create contact handle

Create a new contact handle (WHOIS contact) for domain registration and billing.

Important Restrictions: The following fields CANNOT be changed after creation:

  • role_type (PERS or ORG)
  • organisation
  • firstname
  • lastname

All other fields can be updated later using the update endpoint.

Validation Rules:

  • role_type: Required, must be 'PERS' (personal) or 'ORG' (organization)
  • organisation: Required when role_type is 'ORG', readonly after creation
  • firstname: Required, readonly after creation
  • lastname: Required, readonly after creation
  • street: Required
  • house_number: Required, must contain at least one digit
  • postal: Required, must contain at least one digit
  • city: Required
  • country: Required, must be valid ISO 3166-1 alpha-2 country code
  • email: Required, must be valid email address
  • phone: Required, must be valid international phone number
  • fax: Optional, must be valid international phone number if provided

Error Messages:

  • house_number: "muss eine Ziffer enthalten" (must contain a digit) - when house number has no digits
  • postal: "muss eine Ziffer enthalten" (must contain a digit) - when postal code has no digits
  • organisation: "muss ausgefüllt werden" (must be filled in) - when role_type is ORG but organisation is empty
  • phone: Phone validation errors from phony_plausible gem
  • country: "ist nicht in der Liste enthalten" (is not included in the list) - when country code is invalid

Authorization Requirements:

  • User must be authenticated
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

Handle creation parameters

required
object

Handle creation parameters

role_type
required
string
Enum: "PERS" "ORG"

Contact type. Use PERS for personal contacts, ORG for organizational contacts. Cannot be changed after creation

organisation
string

Organization name. Required when role_type is ORG. Cannot be changed after creation

firstname
required
string

First name of the contact. Cannot be changed after creation

lastname
required
string

Last name of the contact. Cannot be changed after creation

street
required
string

Street name

house_number
required
string

House number. Must contain at least one digit

postal
required
string

Postal/ZIP code. Must contain at least one digit

city
required
string

City name

country
required
string

ISO 3166-1 alpha-2 country code (e.g., DE, US, FR)

email
required
string <email>

Contact email address

phone
required
string

Phone number in international format

fax
string

Fax number in international format (optional)

Responses

Request samples

Content type
application/json
{
  • "handle": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

Show handle details

Show details of a specific contact handle.

Authorization Requirements:

  • User must be authenticated
  • User must own the handle
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the handle to retrieve

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/handles/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "id": 12345,
  • "role_type": "PERS",
  • "organisation": "Acme Corporation",
  • "firstname": "Max",
  • "lastname": "Mustermann",
  • "street": "Musterstraße",
  • "house_number": "42",
  • "postal": "12345",
  • "city": "Berlin",
  • "country": "DE",
  • "email": "max.mustermann@example.com",
  • "phone": "+49 172 4856546",
  • "fax": "+49 30 12485785",
  • "external_id": "LIMA12345",
  • "deleted_at": "2024-10-25T15:30:00+02:00"
}

Update contact handle

Update an existing contact handle. Only updatable fields can be changed.

Important Restrictions: The following fields CANNOT be updated after creation:

  • role_type (PERS or ORG)
  • organisation
  • firstname
  • lastname

These fields are readonly to maintain consistency with domain registry systems.

Updatable Fields:

  • street
  • house_number
  • postal
  • city
  • country
  • email
  • phone
  • fax

Validation Rules:

  • street: Required
  • house_number: Required, must contain at least one digit
  • postal: Required, must contain at least one digit
  • city: Required
  • country: Required, must be valid ISO 3166-1 alpha-2 country code
  • email: Required, must be valid email address
  • phone: Required, must be valid international phone number
  • fax: Optional, must be valid international phone number if provided

Error Messages:

  • house_number: "muss eine Ziffer enthalten" (must contain a digit) - when house number has no digits
  • postal: "muss eine Ziffer enthalten" (must contain a digit) - when postal code has no digits
  • phone: Phone validation errors from phony_plausible gem
  • country: "ist nicht in der Liste enthalten" (is not included in the list) - when country code is invalid

Registry Synchronization: If the handle is registered with a domain registry, the update will be synchronized with the registry.

Authorization Requirements:

  • User must be authenticated
  • User must own the handle
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the handle to update

Request Body schema: application/json
required

Handle update parameters. Only updatable fields should be included

required
object

Handle update parameters. Note: role_type, organisation, firstname, and lastname cannot be updated after creation

street
required
string

Street name

house_number
required
string

House number. Must contain at least one digit

postal
required
string

Postal/ZIP code. Must contain at least one digit

city
required
string

City name

country
required
string

ISO 3166-1 alpha-2 country code (e.g., DE, US, FR)

email
required
string <email>

Contact email address

phone
required
string

Phone number in international format

fax
string

Fax number in international format (optional)

Responses

Request samples

Content type
application/json
{
  • "handle": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update contact handle

Update an existing contact handle. Only updatable fields can be changed.

Important Restrictions: The following fields CANNOT be updated after creation:

  • role_type (PERS or ORG)
  • organisation
  • firstname
  • lastname

These fields are readonly to maintain consistency with domain registry systems.

Updatable Fields:

  • street
  • house_number
  • postal
  • city
  • country
  • email
  • phone
  • fax

Validation Rules:

  • street: Required
  • house_number: Required, must contain at least one digit
  • postal: Required, must contain at least one digit
  • city: Required
  • country: Required, must be valid ISO 3166-1 alpha-2 country code
  • email: Required, must be valid email address
  • phone: Required, must be valid international phone number
  • fax: Optional, must be valid international phone number if provided

Error Messages:

  • house_number: "muss eine Ziffer enthalten" (must contain a digit) - when house number has no digits
  • postal: "muss eine Ziffer enthalten" (must contain a digit) - when postal code has no digits
  • phone: Phone validation errors from phony_plausible gem
  • country: "ist nicht in der Liste enthalten" (is not included in the list) - when country code is invalid

Registry Synchronization: If the handle is registered with a domain registry, the update will be synchronized with the registry.

Authorization Requirements:

  • User must be authenticated
  • User must own the handle
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the handle to update

Request Body schema: application/json
required

Handle update parameters. Only updatable fields should be included

required
object

Handle update parameters. Note: role_type, organisation, firstname, and lastname cannot be updated after creation

street
required
string

Street name

house_number
required
string

House number. Must contain at least one digit

postal
required
string

Postal/ZIP code. Must contain at least one digit

city
required
string

City name

country
required
string

ISO 3166-1 alpha-2 country code (e.g., DE, US, FR)

email
required
string <email>

Contact email address

phone
required
string

Phone number in international format

fax
string

Fax number in international format (optional)

Responses

Request samples

Content type
application/json
{
  • "handle": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Delete contact handle

Soft delete a contact handle. The handle is marked as deleted but may be retained in the database for historical records.

Deletion Behavior:

  • If the handle is not in use and has no historical records, it will be permanently deleted from the database
  • If the handle is referenced by historical records (past orders, invoices, subscriptions), it will be soft-deleted (marked with deleted_at timestamp)
  • If the handle is currently in use, the deletion will fail with a 400 error

Handle is NOT deletable if:

  • It is the user's VAT billing handle
  • It is used as any contact type (owner, admin, tech, zone, billing) for an active domain
  • It is the billing handle for an active (non-cancelled, non-replaced) subscription
  • It is the billing handle for a cloud account
  • It is the billing handle for a pending order

Side Effects:

  • If this handle is the user's default billing handle, the default will be automatically changed to another available handle

Error Messages:

  • base: "ist derzeit in Benutzung" (is currently in use) - when handle cannot be deleted because it's actively used

Authorization Requirements:

  • User must be authenticated
  • User must own the handle
  • Handle must be deletable (not in active use)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the handle to delete

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/handles/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Set default billing handle

Set this handle as the user's default billing handle. The default billing handle is used automatically for new orders and subscriptions.

Authorization Requirements:

  • User must be authenticated
  • User must own the handle
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the handle to set as default

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/handles/12345/default' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

logs

Access server logs including PHP error logs, web server access logs, and error logs. Monitor application behavior, debug issues, and audit server activities with searchable log retrieval.

List PHP error log entries

Retrieve PHP runtime error logs with optional filtering capabilities. Shows errors, warnings, notices, and other PHP-related issues from your applications.

Data Retention:

  • Logs are available for the last 24 hours by default
  • Time filters cannot retrieve logs older than 1 day
  • Logs are displayed in reverse chronological order (newest first)

Validation Rules:

  • script: Maximum 500 characters
  • level: Must be one of the valid PHP error levels
  • message: Maximum 500 characters for filter
  • from_time and to_time: Cannot be older than 1 day
  • Time format: ISO 8601 datetime string

Error Messages:

  • "Script-Filter zu lang (max. 500 Zeichen)" (Script filter too long, max 500 characters)
  • "Ungültiger Error-Level" (Invalid error level)
  • "Nachricht-Filter zu lang (max. 500 Zeichen)" (Message filter too long, max 500 characters)
  • "from_time cannot be older than 1 day"
  • "to_time cannot be older than 1 day"
  • "Invalid from_time format"
  • "Invalid to_time format"
Authorizations:
apiKeyBasicAuth
query Parameters
script
string <= 500 characters
Example: script=/html/index.php

Filter by script path (partial match). Maximum 500 characters.

level
string
Enum: "deprecated" "notice" "info" "warning" "error" "fatal_error" "parse_error"
Example: level=error

Filter by PHP error severity level

message
string <= 500 characters
Example: message=undefined function

Filter by error message content (case-insensitive partial match). Maximum 500 characters.

from_time
string <date-time>
Example: from_time=2024-10-25T14:00:00+02:00

Filter logs from this time onwards (ISO 8601 format). Cannot be older than 1 day. Defaults to 1 day ago if not specified.

to_time
string <date-time>
Example: to_time=2024-10-25T15:00:00+02:00

Filter logs up to this time (ISO 8601 format). Cannot be older than 1 day.

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/php_error_log?script=%2Fhtml%2Findex.php&level=error&message=undefined+function&from_time=2024-10-25T14%3A00%3A00%2B02%3A00&to_time=2024-10-25T15%3A00%3A00%2B02%3A00' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "logs": [
    ]
}

List Apache/nginx access logs

Retrieve Apache/nginx access logs showing HTTP requests made to your websites with optional filtering.

Data Retention:

  • Logs are available for the last 7 days
  • Time filters cannot retrieve logs older than 7 days
  • Default time range: last 1 hour if no time filters specified
  • Maximum 200 log entries returned per request
  • Results are ordered by time (newest first)

Validation Rules:

  • hostname: Maximum 100 characters, alphanumeric with dots, hyphens, and underscores only
  • ip: Maximum 45 characters (supports IPv6), hexadecimal, dots, and colons only
  • request_path: Maximum 500 characters, must start with '/'
  • status: Must be a valid 3-digit HTTP status code (100-599)
  • from_time and to_time: Cannot be older than 7 days
  • Time format: ISO 8601 datetime string or parseable date format

Error Messages:

  • "Hostname filter too long (max 100 characters)"
  • "Invalid hostname format"
  • "IP filter too long"
  • "Invalid IP format"
  • "Request path filter too long (max 500 characters)"
  • "Request path must start with /"
  • "Invalid HTTP status code"
  • "from_time cannot be older than 7 days"
  • "to_time cannot be older than 7 days"
  • "Invalid from_time format"
  • "Invalid to_time format"
Authorizations:
apiKeyBasicAuth
query Parameters
hostname
string <= 100 characters ^[a-zA-Z0-9\.\-_]+$
Example: hostname=example.lima-city.de

Filter by hostname/domain (partial match). Maximum 100 characters, alphanumeric with dots, hyphens, underscores.

ip
string <= 45 characters
Example: ip=192.168

Filter by client IP address (partial match, supports IPv4 and IPv6). Maximum 45 characters.

request_path
string <= 500 characters ^/
Example: request_path=/api/users

Filter by request path (partial match). Must start with '/'. Maximum 500 characters.

status
integer [ 100 .. 599 ]
Example: status=404

Filter by HTTP status code (exact match). Must be a valid 3-digit status code.

from_time
string <date-time>
Example: from_time=2024-10-25T14:00:00+02:00

Filter logs from this time onwards (ISO 8601 format). Cannot be older than 7 days. Defaults to 1 hour ago if not specified.

to_time
string <date-time>
Example: to_time=2024-10-25T15:00:00+02:00

Filter logs up to this time (ISO 8601 format). Cannot be older than 7 days.

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/access_logs?hostname=example.lima-city.de&ip=192.168&request_path=%2Fapi%2Fusers&status=404&from_time=2024-10-25T14%3A00%3A00%2B02%3A00&to_time=2024-10-25T15%3A00%3A00%2B02%3A00' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "logs": [
    ]
}

List Apache/nginx error logs

Retrieve Apache/nginx server error logs showing server-level errors and warnings with optional filtering.

Data Retention:

  • Logs are available for the last 7 days
  • Time filters cannot retrieve logs older than 7 days
  • Default time range: last 1 hour if no time filters specified
  • Maximum 200 log entries returned per request
  • Results are ordered by time (newest first)

Validation Rules:

  • hostname: Maximum 100 characters, alphanumeric with dots, hyphens, and underscores only
  • client_ip: Maximum 45 characters (supports IPv6), hexadecimal, dots, and colons only
  • log_level: Must be one of the valid Apache/nginx log levels
  • module: Maximum 50 characters, alphanumeric with underscores and hyphens only
  • from_time and to_time: Cannot be older than 7 days
  • Time format: ISO 8601 datetime string or parseable date format

Error Messages:

  • "Hostname filter too long (max 100 characters)"
  • "Invalid hostname format"
  • "Client IP filter too long"
  • "Invalid client IP format"
  • "Invalid log level (must be one of: emergency, alert, critical, error, warning, notice, info, debug)"
  • "Module filter too long (max 50 characters)"
  • "Invalid module format"
  • "from_time cannot be older than 7 days"
  • "to_time cannot be older than 7 days"
  • "Invalid from_time format"
  • "Invalid to_time format"
Authorizations:
apiKeyBasicAuth
query Parameters
hostname
string <= 100 characters ^[a-zA-Z0-9\.\-_]+$
Example: hostname=example.lima-city.de

Filter by hostname/domain (partial match). Maximum 100 characters, alphanumeric with dots, hyphens, underscores.

client_ip
string <= 45 characters
Example: client_ip=192.168

Filter by client IP address (partial match, supports IPv4 and IPv6). Maximum 45 characters.

log_level
string
Enum: "emergency" "alert" "critical" "error" "warning" "notice" "info" "debug"
Example: log_level=error

Filter by Apache/nginx error severity level (exact match, case-insensitive)

module
string <= 50 characters ^[a-zA-Z0-9_\-]+$
Example: module=core

Filter by Apache/nginx module name (partial match). Maximum 50 characters.

from_time
string <date-time>
Example: from_time=2024-10-25T14:00:00+02:00

Filter logs from this time onwards (ISO 8601 format). Cannot be older than 7 days. Defaults to 1 hour ago if not specified.

to_time
string <date-time>
Example: to_time=2024-10-25T15:00:00+02:00

Filter logs up to this time (ISO 8601 format). Cannot be older than 7 days.

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/error_logs?hostname=example.lima-city.de&client_ip=192.168&log_level=error&module=core&from_time=2024-10-25T14%3A00%3A00%2B02%3A00&to_time=2024-10-25T15%3A00%3A00%2B02%3A00' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "logs": [
    ]
}

memcache

Manage Memcached caching services for performance optimization. Enable/disable Memcached, monitor cache statistics, and clear cache to improve application response times.

Show memcached status

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/memcached' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "available": true,
  • "enabled": true,
  • "current_size": "128",
  • "socket": "/usr/share/lima/php-deinbenutzername/memcached.sock",
  • "stats": {
    }
}

Enable memcached

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/memcached/enable' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

restores

Restore websites and databases from backups. Monitor restore operations, check restoration status, and manage recovery from specific backup snapshots for disaster recovery and migration scenarios.

List restore requests

List all restore requests (both database and webspace backups) for the authenticated user with pagination support.

Restore Types:

  • Database Restore: Restore a database backup either to a specific database or download as archive
  • Webspace Restore: Restore a webspace backup either to the webspace or download as archive

Restore States:

  • waiting - Restore request is queued and waiting to start
  • running - Restore is currently in progress
  • success - Restore completed successfully
  • failure - Restore failed

Download Availability:

  • Successful download-type restores are available for 5 days after creation
  • After 5 days, the download URL is no longer accessible
  • The downloadable field indicates current availability

Requirements:

  • User must have shared hosting access

Response Structure:

  • Each restore includes information about the source backup (restorable)
  • Progress information (percent, files, bytes) tracks restore operation
  • Target information indicates whether restore is to database/webspace or download
Authorizations:
apiKeyBasicAuth
query Parameters
page
integer >= 1
Default: 1

Page number for pagination (default: 1)

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/restores?page=1' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
Example
{
  • "restores": [
    ],
  • "pagination": {
    }
}

Show restore request

Show details of a specific restore request including progress, state, and target information. The path parameter is the public restore_id string returned by backup restore/download endpoints, not the numeric database ID shown in restore lists.

Use Cases:

  • Monitor progress of an in-progress restore operation
  • Check completion status of a restore
  • Get download URL for successful download-type restores
  • Check if download is still available (within 5-day window)

Progress Tracking:

  • The progress object provides detailed progress information
  • percent field shows completion percentage (0-100)
  • files_restored and bytes_restored track progress at file and byte level
  • Progress updates in real-time during restore operation

Target Information:

  • For database restores: target.database contains target database name
  • For webspace restores: target.webspace is true
  • For downloads: target.download_url contains URL (if still downloadable)
  • target.downloadable indicates if download is still available (5-day limit)

Requirements:

  • User must have shared hosting access
  • User must own the restore request
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Public restore_id returned by backup restore/download endpoints

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/restores/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
Example
{
  • "restore": {
    }
}

ssh

Manage SSH public keys for secure shell access to hosting accounts. Add, list, and revoke SSH keys with automatic fingerprint generation. Support for RSA, DSA, Ed25519, and ECDSA key types for Git, SFTP, and terminal access.

List SSH keys

List all SSH public keys registered for the authenticated user.

SSH keys provide secure authentication for:

  • SSH terminal access to shared hosting accounts (if ssh_enabled is true)
  • Git operations over SSH
  • Rsync file transfers
  • SFTP connections

Each key is identified by its MD5 and SHA256 fingerprints, which are automatically calculated when the key is added.

Use Cases:

  • Managing multiple workstations with different keys
  • Providing developers with access to git repositories
  • Enabling automated deployments via SSH
  • Allowing secure file transfers without password authentication

Key Features:

  • Supports RSA, DSA, Ed25519, and ECDSA key types
  • Automatic fingerprint generation for verification
  • Optional naming for easy identification
  • Per-key SSH access control via ssh_enabled flag
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/ssh_keys' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
[
  • {
    }
]

Add SSH key

Register a new SSH public key for the authenticated user.

The SSH key must be a valid OpenSSH-format public key. The system will automatically parse and validate the key, extract the comment if present, and calculate both MD5 and SHA256 fingerprints.

Supported Key Types:

  • ssh-rsa - RSA keys (legacy but widely supported)
  • ssh-dss - DSA keys (legacy)
  • ssh-ed25519 - Ed25519 keys (recommended, modern and secure)
  • ecdsa-sha2-nistp256 - ECDSA keys with NIST P-256 curve
  • ecdsa-sha2-nistp384 - ECDSA keys with NIST P-384 curve
  • ecdsa-sha2-nistp521 - ECDSA keys with NIST P-521 curve
  • Certificate variants with -cert-v01@openssh.com suffix

Key Format: The text_key field must contain the complete public key in OpenSSH format:

<key-type> <base64-key-data> [optional-comment]

Example valid keys:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDWtLYGThmO7QtLhyHBv+ppzhJDYsFRu4kkYR2LRn6CI user@hostname
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAQBWOR21b8gm37ss3ljwEcbd2Z3Hd2ZoKvSR2hOr7Xr7o...

Validation Rules:

  • text_key: Required, must be valid OpenSSH public key format
  • name: Optional, helps identify the key in listings
  • Key must parse successfully with OpenSSL/Net::SSH
  • Key type must be one of the supported types listed above

Automatic Processing:

  • Comment is extracted from the key text if present
  • MD5 fingerprint is calculated automatically
  • SHA256 fingerprint is calculated automatically
  • Key is validated before storage

Error Messages:

  • 'sieht nicht nach einem gültigen Key aus...' (doesn't look like a valid key) - Key format validation failed
  • 'konnte den Key nicht parsen...' (couldn't parse the key) - OpenSSL/Net::SSH parsing error
  • 'scheint kein gültiger Public-Key-Typ zu sein...' (doesn't seem to be a valid public key type) - Unsupported key type

Security Notes:

  • Only public keys are stored, never private keys
  • Keys are validated before acceptance
  • Ed25519 keys are recommended for best security and performance
  • Each key receives unique fingerprints for verification
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

SSH key creation parameters. The request must be nested under 'ssh_key' to match Rails controller structure.

required
object

SSH key parameters

name
string

Optional human-readable name for the key to help identify it in listings

text_key
required
string

The complete SSH public key in OpenSSH format. Must start with a valid key type (ssh-rsa, ssh-dss, ssh-ed25519, ecdsa-sha2-nistp256/384/521) followed by the base64-encoded key data. Optionally followed by a comment.

Responses

Request samples

Content type
application/json
{
  • "ssh_key": {
    }
}

Response samples

Content type
application/json
{
  • "id": 145612
}

Delete SSH key

Remove an SSH public key from the authenticated user's account.

This action immediately revokes the key's ability to authenticate. Any systems or services using this key will no longer be able to connect.

Warning: This operation is permanent and cannot be undone. If you need the key again, you will have to re-add it.

Impact:

  • SSH login access using this key will be immediately revoked
  • Git operations using this key will fail
  • SFTP/rsync connections using this key will be denied
  • The key will be removed from authorized_keys on all servers

Use Cases:

  • Removing keys for decommissioned workstations
  • Revoking access when a key is compromised
  • Cleaning up unused or outdated keys
  • Managing key rotation policies
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 145612

Unique identifier of the SSH key to delete

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/ssh_keys/145612' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "success": true
}

websites

Manage website hosting, SSL certificates, and web server configuration. Create, update, delete, and monitor websites with support for SSL/TLS, document root configuration, and web space management.

List websites

List all configured websites (virtual hosts) for the authenticated user, including WordPress installations, registered domains, and recently expired domains.

This endpoint provides a comprehensive view of all hosting configurations including subdomains, external domains, and free lima-city subdomains.

Authorization Requirements:

  • User must have shared hosting features enabled
  • Account must be activated

Response includes:

  • All configured websites with their paths and settings
  • Detected WordPress installations
  • Currently registered domains
  • Domains expired within the last 30 days
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/websites' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "websites": [
    ],
  • "wordpress_installations": [
    ],
  • "domains": {
    },
  • "recently_expired_domains": {
    }
}

Update website

Update the configuration of an existing website. You can change the document root path or configure the website as a redirect.

Important Notes:

  • Cannot change content_strategy to 'install' (for new software installations)
  • When changing to 'redirect', the document root will be stored as '{status}:{url}' format
  • When changing to 'path', the specified path must exist in your home directory
  • Changes take effect immediately but may require a few seconds to propagate

Validation Rules:

  • path: Must be a valid directory path within user's home directory (required if content_strategy='path')
  • redirect_status: Must be '301' or '302' (required if content_strategy='redirect')
  • redirect_url: Must be a valid absolute URL (required if content_strategy='redirect')

Error Messages:

  • "liegt nicht im Benutzerverzeichnis" (does not lie in user directory) - Path is outside user's home directory
  • "ist keine gültige URL" (is not a valid URL) - Redirect URL is malformed
  • "ist kein gültiger Wert" (is not a valid value) - Redirect status must be 301 or 302
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the website to update

Request Body schema: application/json
required

Website update parameters

required
object
content_strategy
required
string
Enum: "path" "redirect"

Content delivery strategy for the website

path
string

Document root path relative to user's home directory. Required when content_strategy is 'path'. Must be a valid directory path

redirect_status
string
Enum: "301" "302"

HTTP redirect status code. Required when content_strategy is 'redirect'

redirect_url
string

Target URL for redirect. Required when content_strategy is 'redirect'. Must be a valid absolute URL

Responses

Request samples

Content type
application/json
{
  • "website": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Delete website

Delete a website configuration and its associated resources.

Important Warnings:

  • This action is permanent and cannot be undone
  • If the website is an external domain, associated email transport configuration will also be deleted
  • The actual files in the document root are NOT deleted
  • WordPress installations and other software must be managed separately

Authorization Requirements:

  • User must own the website
  • User must have shared hosting features enabled
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the website to delete

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/websites/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Set website flag

Set a boolean flag on a website configuration.

Available Flags:

  • force_ssl: When 'on', automatically redirects all HTTP requests to HTTPS

Important Notes:

  • Changes take effect within a few seconds
  • For force_ssl to work, a valid SSL certificate must be installed
  • Setting force_ssl='on' is recommended for all production websites

Authorization Requirements:

  • User must own the website
  • User must have shared hosting features enabled
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the website

Request Body schema: application/json
required

Flag to set

flag
required
string
Value: "force_ssl"

Flag name to set

state
required
string
Enum: "on" "off"

New state for the flag

Responses

Request samples

Content type
application/json
{
  • "flag": "force_ssl",
  • "state": "on"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Get subdomain options

Get a list of available domains under which you can create subdomains.

Only domains that are:

  • Owned by the authenticated user
  • In 'requested' state or later
  • Either paid or free domains
  • Not deleted

will be included in the response.

Authorization Requirements:

  • User must have shared hosting features enabled
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/websites/subdomain/new' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

Create subdomain

Create a new subdomain under one of your registered domains. First call GET /websites/subdomain/new to list usable parent domains, then send the selected domain in usercp_create_subdomain_form.domain.

Content Strategy Options:

  • install: Prepare for software installation
  • same_path: Use the same document root as another website (content_path)
  • path: Specify a custom document root path (path)
  • redirect: Configure as HTTP redirect (redirect_status and redirect_url)

Validation Rules:

  • subdomain: 2-120 characters total for final hostname (subdomain + domain)
  • subdomain: Only lowercase letters, numbers, hyphens, and dots
  • subdomain: Must start and end with alphanumeric characters
  • subdomain: Cannot be empty string or single asterisk '*'
  • Final hostname must be unique (not already configured)
  • domain: Must be owned by user and in valid state

Error Messages:

  • "ist keine gültige Subdomain!" (is not a valid subdomain) - Invalid characters or format
  • "ist bereits vergeben" (is already taken) - Subdomain already exists
  • "darf nicht länger als 120 Zeichen sein" (must not be longer than 120 characters) - Length exceeded
  • "nicht erlaubte Domain" (not allowed domain) - Domain not owned or not in valid state

Successful Response: Returns 201 Created with status: ok and the newly created website ID in object.id.

Authorization Requirements:

  • User must have shared hosting features enabled
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

Subdomain creation parameters

required
object
subdomain
required
string

Subdomain prefix (2-120 characters). Must contain only lowercase letters, numbers, hyphens, and dots. Must start and end with alphanumeric. Cannot be empty string or single asterisk

domain
required
string

Parent domain FQDN. Must be a registered, paid or free domain owned by the user

content_strategy
required
string
Enum: "install" "same_path" "path" "redirect"

Content delivery strategy for the website

path
string

Document root path relative to user's home directory. Required when content_strategy is 'path'. Must be a valid directory path

content_path
string

Path to existing content. Used when content_strategy is 'same_path'

redirect_status
string
Enum: "301" "302"

HTTP redirect status code. Required when content_strategy is 'redirect'

redirect_url
string

Target URL for redirect. Required when content_strategy is 'redirect'. Must be a valid absolute URL

Responses

Request samples

Content type
application/json
Example
{
  • "usercp_create_subdomain_form": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

Connect external domain

Connect an external domain (not registered through lima-city) to your hosting account.

Prerequisites:

  • User must have a premium (paid) subscription
  • Domain must be configured in DNS to point to lima-city servers. Use POST /websites/external-domain/check to verify the current DNS requirements before connecting the domain.

Hostname Processing:

  • Leading 'www.' is automatically stripped
  • Can include wildcard prefix '*.' for catch-all subdomains
  • IDN (Internationalized Domain Names) are automatically converted to punycode
  • Must resolve via DNS

Content Strategy Options:

  • install: Prepare for software installation
  • same_path: Use same document root as another website
  • path: Specify a custom document root path
  • redirect: Configure as HTTP redirect

Validation Rules:

  • hostname: Must be valid FQDN or subdomain
  • hostname: Cannot start with http:// or https://
  • hostname: Cannot be a lima-city subdomain
  • hostname: Must not already be configured on any account
  • hostname: Must exist in DNS

Error Messages:

  • "darf nur aus Buchstaben, Zahlen, Bindestrich und Punkten bestehen" (may only consist of letters, numbers, hyphens and dots)
  • "darf nicht mit http:// oder https:// beginnen" (must not start with http:// or https://)
  • "darf nicht mit einem Punkt beginnen" (must not start with a dot)
  • "ist kein gültiger Hostname" (is not a valid hostname)
  • "darf keine lima-city-Domain sein" (must not be a lima-city domain)
  • "ist nicht aufschaltbar: Domain ist bereits registriert" (cannot be connected: domain is already registered)
  • "die Domain X ist bereits auf einem anderem Account aufgeschaltet" (domain X is already connected on another account)
  • "existiert bereits..." (already exists)
  • "existiert nicht" (does not exist)

Authorization Requirements:

  • User must have shared hosting features enabled
  • User must have premium (paid) subscription
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

External domain connection parameters

required
object
hostname
required
string

Fully qualified domain name or subdomain. Must not begin with www. (it will be stripped). Can include wildcard prefix (*.). Must not be a lima-city domain. Must resolve via DNS. May be IDN (will be converted to punycode internally). Cannot start with http:// or https://

use_ipv6
boolean

Whether to enable IPv6 support for this domain

use_email
boolean

Whether to enable email services for this domain (requires premium subscription)

content_strategy
required
string
Enum: "install" "same_path" "path" "redirect"

Content delivery strategy for the website

path
string

Document root path relative to user's home directory. Required when content_strategy is 'path'

content_path
string

Path to existing content. Used when content_strategy is 'same_path'

redirect_status
string
Enum: "301" "302"

HTTP redirect status code. Required when content_strategy is 'redirect'

redirect_url
string

Target URL for redirect. Required when content_strategy is 'redirect'. Must be a valid absolute URL with no local hostnames

Responses

Request samples

Content type
application/json
{
  • "website": {
    }
}

Response samples

Content type
application/json
{
  • "id": 12345
}

Check external domain DNS

Check if an external domain's DNS records are correctly configured to work with lima-city hosting.

The response shows whether the configured DNS records satisfy the current requirements for website hosting, optional IPv6 support, and optional email reception.

Error Messages:

  • "ist nicht korrekt für IPv4 konfiguriert, siehe Tabelle!" (is not correctly configured for IPv4, see table)
  • "ist nicht korrekt für IPv6 konfiguriert, siehe Tabelle!" (is not correctly configured for IPv6, see table)
  • "ist nicht korrekt für Mail-Empfang konfiguriert, siehe Tabelle!" (is not correctly configured for mail reception, see table)
  • "kann nicht aufgelöst werden" (cannot be resolved) - DNS resolution failed

Authorization Requirements:

  • User must have shared hosting features enabled
  • User must have premium subscription
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

Domain to check

required
object
hostname
required
string

Fully qualified domain name to check

use_ipv6
boolean

Whether to check IPv6 DNS records

use_email
boolean

Whether to check MX email records

Responses

Request samples

Content type
application/json
{
  • "website": {
    }
}

Get free subdomain options

Get available options for creating a free lima-city subdomain.

Returns:

  • List of available free subdomain suffixes as [display_name, domain] pairs
  • Map of your existing websites with their paths, useful for content_strategy: same_path

Free Subdomain Suffixes: The current suffix list is returned by this endpoint. Examples include lima.zone, lima-city.rocks, webspace.rocks, 4lima.de, and de.cool.

Vanity domains are marked with a ¹ indicator in the display name.

Authorization Requirements:

  • User must have shared hosting features enabled
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/websites/lima-subdomain/new' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create free subdomain

Create a free subdomain on one of lima-city's vanity domains. First call GET /websites/lima-subdomain/new to get the currently available suffixes, then send the chosen value in usercp_create_free_subdomain_interaction.domain.

Subdomain Limits:

  • Maximum 25 free subdomains per user
  • This limit applies to all lima-city subdomains combined

Reserved Prefixes: The following prefixes cannot be used:

  • lima-city, limacity
  • blog, webmaster, system
  • www, mail, mx
  • pma, phpmyadmin, mysql
  • ftp, filemanager
  • secure, pay
  • Any prefix starting with 'system-'

Validation Rules:

  • prefix: 2-64 characters
  • prefix: Only lowercase letters, numbers, and hyphens (no dots allowed)
  • prefix: Must start and end with alphanumeric characters
  • Combined hostname (prefix.domain) must not exceed 120 characters

Error Messages:

  • "ist keine gültige Subdomain" (is not a valid subdomain) - Invalid format
  • "darf keinen Punkt enthalten" (must not contain a dot) - Dots not allowed in prefix
  • "ist bereits belegt" (is already taken) - Subdomain already exists
  • "ist für interne Nutzung reserviert" (is reserved for internal use) - Reserved word or system- prefix
  • "darf nicht länger als 120 Zeichen sein" (must not be longer than 120 characters) - Total length exceeded
  • "ist nicht registrierbar, Dein Limit von 25 kostenlosen Domain ist bereits erreicht!" (cannot be registered, your limit of 25 free domains is already reached)

Content Strategy Options:

  • install: Prepare for software installation
  • same_path: Use same document root as another website (content_path)
  • path: Specify a custom document root path (path)
  • redirect: Configure as HTTP redirect (redirect_status and redirect_url)

Successful Response: Returns 201 Created with status: ok and the newly created website ID in object.id.

Authorization Requirements:

  • User must have shared hosting features enabled
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

Free subdomain creation parameters

required
object
prefix
required
string

Subdomain prefix (2-64 characters). Must contain only lowercase letters, numbers, and hyphens. Must start and end with alphanumeric. Cannot contain dots. Cannot start with 'system-'. Cannot be reserved words (lima-city, limacity, blog, webmaster, system, www, mail, mx, pma, phpmyadmin, mysql, ftp, filemanager, secure, pay). Limited to 25 free subdomains per user

domain
required
string
Enum: "4lima.de" "12hp.de" "2ix.de" "lima-city.at" "4lima.at" "12hp.at" "2ix.at" "lima-city.ch" "4lima.ch" "12hp.ch" "2ix.ch" "1337.pictures" "clan.rip" "lima-city.rocks" "webspace.rocks" "lima.zone" "de.cool"

Free subdomain suffix from lima-city's vanity domains

content_strategy
required
string
Enum: "install" "same_path" "path" "redirect"

Content delivery strategy for the website

path
string

Document root path relative to user's home directory. Required when content_strategy is 'path'

content_path
string

Path to existing content. Used when content_strategy is 'same_path'

redirect_status
string
Enum: "301" "302"

HTTP redirect status code. Required when content_strategy is 'redirect'

redirect_url
string

Target URL for redirect. Required when content_strategy is 'redirect'

Responses

Request samples

Content type
application/json
Example
{
  • "usercp_create_free_subdomain_interaction": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

Validate free subdomain prefix

Check if a free subdomain prefix is valid and available before creating it.

This endpoint performs validation without actually creating the subdomain, allowing users to check availability in real-time.

Validation Checks:

  • Prefix format and character requirements
  • Availability (not already taken)
  • Not a reserved word
  • User hasn't exceeded 25 subdomain limit
  • Total hostname length under 120 characters

Authorization Requirements:

  • User must have shared hosting features enabled
Authorizations:
apiKeyBasicAuth
query Parameters
prefix
required
string
Example: prefix=myapp

Subdomain prefix to validate

domain
required
string
Enum: "4lima.de" "12hp.de" "2ix.de" "lima-city.at" "4lima.at" "12hp.at" "2ix.at" "lima-city.ch" "4lima.ch" "12hp.ch" "2ix.ch" "1337.pictures" "clan.rip" "lima-city.rocks" "webspace.rocks" "lima.zone" "de.cool"
Example: domain=lima.zone

Free subdomain suffix

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/websites/lima-subdomain/status?prefix=myapp&domain=lima.zone' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "valid": true,
  • "errors": {
    }
}

Get website statistics

Retrieve traffic statistics for all websites on the account for the last 90 days.

Statistics Include:

  • Page views (human visitors)
  • Page views from bots/robots
  • Total HTTP requests
  • Robot HTTP requests
  • Traffic volume in bytes
  • Robot traffic volume in bytes

Response Details:

  • Data is aggregated daily
  • Covers last 90 days from today

Response Formats:

  • JSON: Returns stats array with website identifiers
  • CSV: Downloadable file with all statistics in tabular format
  • HTML: Web interface for viewing statistics (when not XHR request)

CSV Column Headers:

  • website: Domain name
  • date: Date of statistics
  • page_views: Human page views
  • page_views_robots: Robot page views
  • hits: Total requests
  • hits_robots: Robot requests
  • traffic_mb: Traffic in megabytes
  • traffic_mb_robots: Robot traffic in megabytes

Authorization Requirements:

  • User must have shared hosting features enabled
Authorizations:
apiKeyBasicAuth
header Parameters
Accept
string
Default: application/json
Enum: "application/json" "text/csv" "text/html"

Response format (application/json for JSON, text/csv for CSV download)

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/websites/statistics' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
{
  • "stats": [
    ],
  • "vhosts": [
    ]
}

webspace_backups

Create, list, restore, and download backups of your website files and content. Full file backup management with point-in-time recovery, directory-level restoration, and download support for archival purposes.

List webspace backups

List all automatic webspace backups for the authenticated user with pagination support.

Important Notes:

  • Backups are automatically created by the system
  • Backups older than 90 days are automatically marked as 'deleted'
  • Backups older than 1 year are permanently removed
  • Includes count of currently running restore operations

Requirements:

  • User must have shared hosting access
  • User must have premium subscription (402 error if not premium)

Data Retention:

  • Complete backups are kept for 90 days
  • After 90 days, backups are marked as 'deleted' but metadata retained
  • After 1 year, all backup records are permanently deleted
Authorizations:
apiKeyBasicAuth
query Parameters
page
integer >= 1
Default: 1

Page number for pagination (default: 1)

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/webspace_backups?page=1' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "webspace_backups": [
    ],
  • "restore_count": 2,
  • "pagination": {
    }
}

Show webspace backup

Show details of a specific webspace backup. Currently returns a simple status confirmation.

Important Notes:

  • Backup must belong to the authenticated user
  • Returns simple status response (full details available via list endpoint)

Requirements:

  • User must have shared hosting access
  • User must have premium subscription (402 error if not premium)
  • User must own the backup
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 54321

Unique identifier of the webspace backup

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/webspace_backups/54321' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Browse webspace backup content

Retrieve the file and folder structure within a webspace backup. This endpoint enables browsing backup contents to select specific files/folders for restore.

Important Notes:

  • The folder parameter '#' represents the root directory
  • Paths are cleaned and normalized using Pathname.cleanpath
  • Results are sorted with directories first, then files
  • Each item includes full path (id), display name (text), type, size, and modification time

Usage:

  • Use folder='#' to browse the root directory
  • Use folder='path/to/dir' to browse subdirectories
  • The 'id' field in responses can be used as the folder parameter for deeper navigation
  • The 'id' field values can also be used in the path_list for restore operations

Requirements:

  • User must have shared hosting access
  • User must have premium subscription (402 error if not premium)
  • User must own the backup
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 54321

Unique identifier of the webspace backup

query Parameters
folder
string
Default: "#"
Example: folder=default-website

Folder path to browse within the backup. Use '#' for root directory, or a relative path like 'default-website/wp-content' for subdirectories

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/webspace_backups/54321/content?folder=%23' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Restore or download webspace backup

Restore selected files and folders from a webspace backup either to a ZIP archive for download or directly back to webspace. For customers who want to download backups, use this endpoint with restore.target: download.

Process Flow for Downloads:

  1. Browse selectable paths with GET /webspace_backups/{id}/content?folder=#
  2. Send POST /webspace_backups/{id}/restore with restore.target: download and restore.path_list
  3. The response returns object.restore_id
  4. Poll GET /restores/{restore_id} until state is success
  5. Download the ZIP from restore.target.download_url while restore.target.downloadable is true

Target Types:

  • download: Creates a ZIP archive containing selected files/folders. Archive is available for download for 5 days once state becomes success.
  • webspace: Restores files/folders directly to user's webspace. WARNING: This will overwrite existing files with the same paths!

Important Notes:

  • This is an asynchronous operation - use object.restore_id to track progress at /restores/{restore_id}
  • Path validation ensures paths don't escape user directory (must stay within /theuser/)
  • Empty path strings are automatically filtered out
  • Paths should match the id values returned from the /content endpoint
  • For webspace target, files are restored to their original locations (overwrites existing)
  • For download target, a ZIP archive is created containing the requested files/folders
  • Download archives are available for 5 days after completion

Validation Rules:

  • target: Required, must be download or webspace
  • path_list: Required, must be an array of valid paths
  • Each path in path_list must be a valid path that doesn't escape user directory

Error Messages:

  • "ist keine Liste" (is not a list) - path_list is not an array
  • "{path} ist kein gültiger Pfad" ({path} is not a valid path) - path validation failed, possibly trying to escape user directory

Requirements:

  • User must have shared hosting access
  • User must have premium subscription (402 error if not premium)
  • User must own the backup
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 54321

Unique identifier of the webspace backup to restore from

Request Body schema: application/json
required

Restore parameters specifying target type and file/folder paths

required
object

Nested restore parameters matching controller params.require(:restore) structure

target
required
string
Enum: "download" "webspace"

Restore target type. 'download' creates a ZIP archive for download, 'webspace' restores files directly to user's webspace (overwrites existing files)

path_list
required
Array of strings

List of file/folder paths to restore from the backup. Paths are relative to backup root and must not escape user directory. Empty strings are filtered out

Responses

Request samples

Content type
application/json
Example
{
  • "restore": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

domains

Manage domain names, DNS configuration, transfers, and renewals

List all domains

Retrieve a list of all domains owned by the authenticated user.

This endpoint returns both active and deleted domains with specific filtering:

  • Active domains: Not deleted, not cancelled, with expiration dates
  • Deleted domains: Backordered domains deleted within the last 30 days

Domains are sorted alphabetically by domain name (sld) and TLD.

Domain States:

  • registered: Domain is active and fully registered
  • backorder_pending: Domain registration requested but not yet completed
  • in_transfer: Domain transfer is in progress
  • deleted: Domain has been deleted (shown for 30 days after deletion)

Authorization: Requires valid API key or user authentication.

Authorizations:
apiKeyBasicAuth
query Parameters
object
Example: com=&de=

Filter domains by TLD (top-level domain). Provide TLD as key in the query parameters.

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/domains?tld_filter=%7B%22com%22%3D%3E%22%22%2C+%22de%22%3D%3E%22%22%7D' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

Start domain verification (send SMS code)

Initiate domain verification by sending a 6-digit verification code via SMS to a European phone number.

Verification Process:

  1. Submit phone number in international format
  2. System validates number and checks rate limits
  3. 6-digit code is generated and sent via SMS
  4. Code is valid for 10 minutes
  5. Phone number is stored in session for step 2

Phone Number Requirements:

  • Must be in international format: +xx or 00xx
  • Must be from a European Union country
  • Minimum 6 characters
  • Not on blacklist (VoIP numbers, temporary numbers blocked)
  • Not already associated with another lima-city account

Rate Limits:

  • Maximum 5 SMS per 3 minutes per user
  • Maximum 50 SMS per 24 hours per user

Validation Rules:

  • Phone must have clear country code prefix
  • Must be plausible phone number format
  • Must be from EU country (specific allowed prefixes)
  • Cannot be on internal blacklist
  • Cannot be already verified by another user

Error Messages:

  • "hat keine eindeutige Länder-Angabe: bitte benutze +xx oder 00xx" (Has no clear country code: please use +xx or 00xx)
  • "kann nicht für die Verifizierung benutzt werden" (Cannot be used for verification) - Blacklisted or non-EU
  • "ist bereits bei einem anderen Account in Verwendung" (Is already in use by another account)
  • "rate_limited" - Too many attempts (HTTP 429)

Authorization: Requires valid user authentication.

Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required
required
object

Step 1 verification parameters

phone
required
string

European phone number in international format with country code (+xx or 00xx). Must be from an EU country, meet the minimum length requirement, and be eligible for SMS verification.

Responses

Request samples

Content type
application/json
{
  • "usercp_domain_verification_step1": {
    }
}

Response samples

Content type
application/json
{
  • "phone": "+49 176 12345678"
}

Complete domain verification with SMS code

Complete the domain verification process by submitting the 6-digit code received via SMS.

Code Validation:

  • Code must match a code sent to the phone number from step 1
  • Verification attempts are rate limited

After Successful Verification:

  • Phone number is linked to the account
  • Domain registrations that were blocked by missing verification can proceed

Error Messages:

  • "ist nicht korrekt" (Is not correct) - Invalid or expired code
  • "rate_limited" - Too many verification attempts (HTTP 429)

Authorization: Requires valid user authentication and active session with phone number from step 1.

Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required
required
object

Step 2 verification parameters

code
required
string

6-digit verification code received via SMS.

Responses

Request samples

Content type
application/json
{
  • "usercp_domain_verification_step2": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Get domain details

Retrieve detailed information about a specific domain.

Domain Identification:

  • Use numeric domain ID, or
  • Use fully qualified domain name (e.g., 'example.com')

Returned Information:

  • Registration status and dates
  • Billing status and payment information
  • DNS configuration (auto or custom nameservers)
  • Transfer status (if applicable)
  • Auto-renewal configuration
  • Expiration dates and renewability

Authorization: Requires valid API key or user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name (e.g., 'example.com')

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/domains/example.com' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "domain": {
    }
}

Delete an inclusive premium domain

Mark an inclusive premium domain for automatic expiration (auto-expire).

Important Notes:

  • This endpoint is specifically for domains included in premium subscriptions
  • Sets the domain's auto_renew_mode to 'inclusive_expire'
  • Domain will not be automatically renewed when it expires
  • An email notification is sent to the user confirming the expiration request
  • The domain remains active until its natural expiration date
  • This operation cannot be used for regular paid domains

Use Case: Users with premium hosting subscriptions that include free domains can use this endpoint to let those domains expire when canceling or downgrading their subscription.

Authorization: Requires valid user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/domains/example.com' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Get DKIM keys for a domain

Retrieve DKIM (DomainKeys Identified Mail) keys configured for the domain.

DKIM Overview:

  • DKIM is used to authenticate outgoing emails
  • lima-city automatically creates DKIM keys for all domains
  • Keys are automatically added to DNS when using lima-city nameservers
  • For external DNS, use the provided DNS records to configure manually

Key Information Returned:

  • Public key for DNS TXT record
  • Selector (used in DNS record name: selector._domainkey.domain.com)
  • Complete DNS record format for easy configuration

Authorization: Requires valid user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/domains/example.com/dkim_keys' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "dkim_keys": [
    ]
}

Request domain auth code for transfer-out

Request the authorization code (auth code/EPP code) for transferring the domain to another registrar.

Security Requirements:

  • Two-factor authentication token required (via before_action)
  • User's account password required for verification
  • Auth code is retrieved from registrar and sent via email

Process:

  1. User provides password and optional feedback
  2. System verifies password
  3. Auth code is retrieved from domain registrar (RRPProxy or Antagus)
  4. Auth code is sent to user's email address
  5. Activity is logged in user notes

Important Notes:

  • This action requires 2FA verification if enabled on account
  • Auth code email is sent to the email address on file
  • Feedback message (if provided) is stored in user notes
  • Auth code remains valid according to registrar's policy

Validation Rules:

  • Password must match user's current password
  • Auth code must be successfully retrieved from registrar

Error Messages:

  • Password validation errors (German: "Passwort ist ungültig")
  • "AuthInfo is empty" - Failed to retrieve auth code from registrar

Authorization: Requires valid user authentication with 2FA verification. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Request Body schema: application/json
required
required
object

Auth info request parameters

password
required
string

User's lima-city account password for verification

feedback
string

Optional feedback message about why the auth info is needed (stored in user notes)

Responses

Request samples

Content type
application/json
{
  • "request": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Restart failed domain transfer

Restart a domain transfer that encountered an error or is stuck in pending state.

Use Cases:

  • Transfer failed due to incorrect auth code (now corrected)
  • Transfer stuck in pending state
  • Registrar reported an error that has been resolved

Process:

  1. Clears the order_error field on the domain
  2. Queues a DomainRegistrationWorker to retry the transfer
  3. Worker executes after 30 seconds

Requirements:

  • Domain must be in transfer mode (TRANSFER-IN)
  • Domain must be paid
  • Domain must be in backorder_pending state

Authorization: Requires valid user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/domains/example.com/restart_transfer' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "result": "ok"
}

Update DNS server configuration

Update the DNS server (nameserver) configuration for a domain.

DNS Modes:

  • auto: Use lima-city nameservers (ns1.lima-city.de, ns2.lima-city.de, ns3.lima-city.de)
  • custom: Use external nameservers (must provide at least 2 valid nameservers)

Switching to Auto Mode:

  • Removes custom nameserver configuration
  • DNS records managed via lima-city DNS interface
  • DNSSEC keys (if any) remain but are managed by lima-city

Switching to Custom Mode:

  • Requires at least 2 valid nameserver hostnames
  • Nameservers must resolve to IP addresses
  • Nameservers must respond to DNS queries for the domain
  • Can optionally provide up to 3 DNSSEC keys
  • DNS records cannot be managed via lima-city interface

Nameserver Validation:

  • Must be hostnames (not IP addresses)
  • Must resolve via DNS
  • Must respond to DNS queries
  • Must serve SOA records for the domain

DNSSEC Key Validation:

  • Maximum 3 keys allowed
  • Flags: Must be 256 (ZSK) or 257 (KSK)
  • Protocol: Must be 3
  • Algorithm: Must be 1-16 (see DNSSEC algorithm numbers)
  • Public key: Must be valid Base64

Error Messages:

  • "ist eine IP-Adresse, muss aber ein Hostname sein" (Is an IP address, but must be a hostname)
  • "kann nicht aufgelöst werden" (Cannot be resolved)
  • "beantwortet keine DNS-Anfragen für [domain]" (Does not answer DNS queries for [domain])
  • "antwortet nicht auf DNS-Anfragen" (Does not respond to DNS queries)
  • "maximal 3 DNSSEC-Schlüssel erlaubt" (Maximum 3 DNSSEC keys allowed)
  • "Schlüssel #X (Flags) muss 256 oder 257 sein" (Key #X (Flags) must be 256 or 257)
  • "Schlüssel #X (Protocol) muss 3 sein" (Key #X (Protocol) must be 3)
  • "Schlüssel #X (Algorithm) muss zwischen 1 und 16 liegen" (Key #X (Algorithm) must be between 1 and 16)
  • "Schlüssel #X (Public Key) enthält ungültige Zeichen" (Key #X (Public Key) contains invalid characters)

Authorization: Requires valid user authentication. User must own the domain and DNS must not be blocked.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Request Body schema: application/json
required
required
object

DNS server configuration parameters

dns_mode
required
string
Enum: "auto" "custom"

DNS hosting mode: 'auto' uses lima-city nameservers (ns1/ns2/ns3.lima-city.de), 'custom' uses external nameservers. When switching to 'auto', all nameserver fields are ignored.

nameserver1
string

First nameserver hostname (required if dns_mode is 'custom'). Must be a valid hostname that resolves and responds to DNS queries for the domain. IP addresses are not allowed.

nameserver2
string

Second nameserver hostname (required if dns_mode is 'custom'). Must be a valid hostname that resolves and responds to DNS queries for the domain. IP addresses are not allowed.

nameserver3
string

Third nameserver hostname (optional). Must be a valid hostname that resolves and responds to DNS queries for the domain. IP addresses are not allowed.

nameserver4
string

Fourth nameserver hostname (optional). Must be a valid hostname that resolves and responds to DNS queries for the domain. IP addresses are not allowed.

nameserver5
string

Fifth nameserver hostname (optional). Must be a valid hostname that resolves and responds to DNS queries for the domain. IP addresses are not allowed.

Array of objects (DnssecKey) <= 3 items

Array of DNSSEC keys for custom nameservers (optional, max 3 keys). Only valid when dns_mode is 'custom'.

Array (<= 3 items)
flags
required
integer
Enum: 256 257

DNSSEC key flags: 256 for Zone Signing Key (ZSK), 257 for Key Signing Key (KSK)

protocol
required
integer
Value: 3

DNSSEC protocol (must be 3)

algorithm
required
integer [ 1 .. 16 ]

DNSSEC algorithm number (1-16). Common values: 5=RSASHA1, 7=RSASHA1-NSEC3-SHA1, 8=RSASHA256, 13=ECDSAP256SHA256, 14=ECDSAP384SHA384

public_key
required
string

Base64-encoded public key (must contain only Base64 characters: A-Z, a-z, 0-9, +, /, =)

Responses

Request samples

Content type
application/json
{
  • "dns_server": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update domain authorization code

Update the authorization code (auth code/EPP code) for a pending domain transfer.

Purpose: Provide or correct the auth code needed to complete a domain transfer from another registrar.

Requirements:

  • Domain must be a pending transfer
  • Auth code must not be empty
  • Domain must require auth info

After Update:

  • The transfer can continue with the updated auth code
  • Domain remains in transfer state until registrar confirms

Validation Rules:

  • Auth code must be present (not blank)

Error Messages:

  • "muss ausgefüllt werden" (Must be filled out) - Empty auth code

Authorization: Requires valid user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Request Body schema: application/json
required
auth_info
required
string

Authorization code (auth code/EPP code) provided by the previous registrar. Required for domain transfers. Must not be empty.

Responses

Request samples

Content type
application/json
{
  • "auth_info": "Xyz789Abc!123"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Add domain renewal to cart

Add a renewal order for this domain to the shopping cart.

Important Notes:

  • This endpoint redirects (HTTP 302) rather than returning JSON
  • Renewal is added to cart but not immediately processed
  • User must complete checkout to finalize renewal
  • Each renewal extends the domain by 1 year

Renewability Requirements:

  • For most TLDs: Domain must be ordered and registered
  • For .tk domains: Domain must be ordered and not deleted

Response Behavior:

  • Success: Redirects to cart page with notice (German: "Domain-Verlängerung zum Warenkorb hinzugefügt")
  • Not renewable: Redirects to domain show page with error (German: "Domain kann nicht verlängert werden")
  • Invalid cart item: Redirects to cart with error message from ActiveRecord

Authorization: Requires valid user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/domains/example.com/renew' \
  --user 'api:YOUR_API_KEY'

Toggle auto-renew on/off

Enable or disable automatic renewal for a single domain.

Important Requirements:

  • To enable auto-renew: User must have a default payment method configured
  • To disable auto-renew: No special requirements

Auto-Renewal Behavior:

  • Enabled: Domain automatically renews ~2 weeks before expiration
  • Disabled: Domain must be manually renewed before expiration

Response Statuses:

  • ok: Operation successful
  • payment_method_required: Cannot enable auto-renew without payment method (HTTP 403)

Authorization: Requires valid user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Request Body schema: application/json
required
enabled
required
boolean

Whether to enable (true) or disable (false) automatic renewal. Enabling auto-renew requires a default payment method to be set on the account.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update payment method for domain

Change the payment method used for automatic renewals of this domain. This is a web endpoint referenced in routes but implementation details suggest it updates the domain's payment_method_id.

Use Case: User wants to use a different payment method for this specific domain's renewals.

Authorization: Requires valid user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Request Body schema: application/json
required
payment_method_id
integer

ID of the payment method to use for this domain

Responses

Request samples

Content type
application/json
{
  • "payment_method_id": 12345
}

Update billing handle for domain

Change the billing contact handle associated with this domain. This is a web endpoint referenced in routes.

Use Case: User wants to use a different billing contact for this domain (e.g., company billing info instead of personal).

Authorization: Requires valid user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Request Body schema: application/json
required
billing_handle_id
integer

ID of the handle to use as billing contact

Responses

Request samples

Content type
application/json
{
  • "billing_handle_id": 67890
}

Restore deleted backordered domain

Create an order to restore a deleted domain that was previously backordered (registered through lima-city).

Requirements:

  • Domain must be backordered (registered via lima-city)
  • Domain must be deleted
  • Domain must not be hidden
  • Domain must be restorable (within 30-day redemption period)

Process:

  1. Validates domain is eligible for restoration
  2. Creates a restore order via DomainRestoreOrderBuilder
  3. Returns order ID for payment processing
  4. After payment, domain restoration is initiated with registrar

Restore Pricing: Restoration typically costs more than regular renewal due to registrar redemption fees.

Authorization: Requires valid user authentication. User must own the domain.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Domain ID (integer)

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/domains/12345/restore' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok",
  • "order_id": 67890
}

dns

Manage DNS records

List DNS records for a domain

Retrieve all DNS records configured for a domain.

Requirements:

  • Domain must use lima-city nameservers (dns_mode: 'auto')
  • User's DNS management must not be blocked

Returned Records:

  • All record types: A, AAAA, CNAME, MX, TXT, SRV, NS, SOA, CAA, TLSA, DS, DNSKEY
  • Includes system-managed records (NS, SOA)
  • Includes user-created records

Record Information:

  • Record ID for updates/deletes
  • Name (hostname)
  • Type
  • Content (value)
  • TTL (time to live)
  • Priority (for MX and SRV records)

Domain Identification:

  • Use numeric domain ID, or
  • Use fully qualified domain name (e.g., 'example.com')

Authorization: Requires valid API key or user authentication. User must own the domain. DNS must not be blocked.

Authorizations:
apiKeyBasicAuth
path Parameters
domain_id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/domains/example.com/records' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a DNS record

Create a new DNS resource record for the domain.

Requirements:

  • Domain must use lima-city nameservers (dns_mode: 'auto')
  • User's DNS management must not be blocked

Record Types Supported:

  • A: IPv4 address
  • AAAA: IPv6 address
  • CNAME: Canonical name (alias)
  • MX: Mail exchanger
  • TXT: Text record
  • SRV: Service record
  • CAA: Certification Authority Authorization
  • TLSA: TLS authentication
  • DS: Delegation Signer (for subdomains only)
  • DNSKEY: DNS Key (for subdomains only)

Name Input Shortcuts:

  • Use '@' to create record for apex domain (example.com)
  • Use 'www' to create record for www.example.com
  • Use full hostname to be explicit
  • Trailing dots are not allowed
  • System automatically appends domain name if needed

Validation Rules:

  • A records: Must be valid IPv4 address
  • AAAA records: Must be valid IPv6 address
  • CNAME records: Cannot be created for apex domain, must be valid hostname
  • MX records: Requires priority (0-100), must be valid hostname
  • SRV records: Requires priority (0-100), content format 'weight port target'
  • TXT records: Automatically quoted if needed
  • TTL: Must be between 60 and 86400 seconds
  • NS records: Cannot be created for apex domain via API
  • DS/DNSKEY records: Cannot be created for apex domain

After Creation:

  • SOA serial number is automatically incremented
  • Changes propagate according to TTL values

Error Messages:

  • "muss mit .[domain] enden" (Must end with .[domain])
  • "darf nicht mit einem Punkt enden" (Must not end with a dot)
  • "darf nicht mit einem Punkt starten" (Must not start with a dot)
  • "darf kein leeres Label enthalten" (Must not contain empty label)
  • "darf kein Leerzeichen enthalten" (Must not contain spaces)
  • "ist keine gültige IPv4-Adresse" (Is not a valid IPv4 address)
  • "ist keine gültige IPv6-Adresse" (Is not a valid IPv6 address)
  • "ist nicht gültig: ein CNAME-Record darf nicht für die Haupt-Domain angelegt werden" (Cannot create CNAME for apex domain)
  • "ist nicht gültig: ein NS-Record kann nicht für die APEX-Domain angelegt werden" (Cannot create NS record for apex domain)
  • "ist nicht gültig: ein DS- oder DNSKEY-Record kann nicht für die Hauptdomain angelegt werden" (Cannot create DS/DNSKEY for apex)
  • "muss ein gültiger Hostname sein" (Must be a valid hostname)
  • "muss aus drei Werten (Gewicht, Port, Hostname) bestehen" (Must consist of three values: weight, port, hostname)

Authorization: Requires valid API key or user authentication. User must own the domain. DNS must not be blocked.

Authorizations:
apiKeyBasicAuth
path Parameters
domain_id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Request Body schema: application/json
required
required
object (DnsRecordInput)

DNS record input parameters

name
required
string

Record name. Use '@' for apex domain, or provide subdomain. Automatically expanded to full hostname.

type
required
string
Enum: "A" "AAAA" "CNAME" "MX" "TXT" "SRV" "SPF" "CAA" "TLSA" "DS" "DNSKEY"

DNS record type

content
required
string

Record content (format depends on type)

ttl
required
integer [ 60 .. 86400 ]

Time to live in seconds (60-86400)

priority
integer [ 0 .. 100 ]

Priority (required for MX and SRV records)

Responses

Request samples

Content type
application/json
{
  • "nameserver_record": {
    }
}

Response samples

Content type
application/json
{
  • "record": {
    }
}

Reset DNS zone to defaults

Reset the DNS zone to default configuration, removing all custom records and recreating standard records.

Warning: This operation is destructive and cannot be undone!

Process:

  1. Deletes all existing DNS records for the domain
  2. Creates new DNS zone with default records:
    • SOA record
    • NS records (ns1/ns2/ns3.lima-city.de)
    • Default A record pointing to lima-city hosting
    • Default MX records for mail.lima-city.de
    • Default TXT records (SPF, etc.)
  3. DKIM keys are preserved and re-added

Use Cases:

  • Reset after misconfiguration
  • Start fresh with default settings
  • Restore after accidental deletion of critical records

Requirements:

  • Domain must use lima-city nameservers
  • User's DNS management must not be blocked

Authorization: Requires valid user authentication. User must own the domain. DNS must not be blocked.

Authorizations:
apiKeyBasicAuth
path Parameters
domain_id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/domains/example.com/records/reset_dns' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Get DNS record details

Retrieve details of a specific DNS record.

Requirements:

  • Domain must use lima-city nameservers
  • User's DNS management must not be blocked

Authorization: Requires valid API key or user authentication. User must own the domain. DNS must not be blocked.

Authorizations:
apiKeyBasicAuth
path Parameters
domain_id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

id
required
integer
Example: 98765

DNS record ID

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/domains/example.com/records/98765' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "record": {
    }
}

Update a DNS record

Update an existing DNS resource record.

Requirements:

  • Domain must use lima-city nameservers
  • User's DNS management must not be blocked
  • Same validation rules as record creation apply

Updatable Fields:

  • name: Record hostname
  • type: Record type (changing type effectively creates a different record)
  • content: Record value
  • ttl: Time to live (60-86400 seconds)
  • priority: Priority for MX/SRV records (0-100)

Important Notes:

  • Changing record type may require changing content format
  • All validation rules from creation apply
  • SOA serial is automatically incremented after update
  • Changes propagate according to old TTL value first, then new TTL

Same Validation as Creation:

  • See POST /domains/{domain_id}/records for complete validation rules

Authorization: Requires valid API key or user authentication. User must own the domain. DNS must not be blocked.

Authorizations:
apiKeyBasicAuth
path Parameters
domain_id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

id
required
integer
Example: 98765

DNS record ID

Request Body schema: application/json
required
required
object (DnsRecordInput)

DNS record input parameters

name
required
string

Record name. Use '@' for apex domain, or provide subdomain. Automatically expanded to full hostname.

type
required
string
Enum: "A" "AAAA" "CNAME" "MX" "TXT" "SRV" "SPF" "CAA" "TLSA" "DS" "DNSKEY"

DNS record type

content
required
string

Record content (format depends on type)

ttl
required
integer [ 60 .. 86400 ]

Time to live in seconds (60-86400)

priority
integer [ 0 .. 100 ]

Priority (required for MX and SRV records)

Responses

Request samples

Content type
application/json
{
  • "nameserver_record": {
    }
}

Response samples

Content type
application/json
{
  • "record": {
    }
}

Delete a DNS record

Delete an existing DNS resource record.

Requirements:

  • Domain must use lima-city nameservers
  • User's DNS management must not be blocked

Important Notes:

  • This operation cannot be undone
  • SOA serial is automatically incremented after deletion
  • System-managed records (NS, SOA for apex domain) cannot be deleted
  • Changes propagate according to the record's TTL value

Authorization: Requires valid API key or user authentication. User must own the domain. DNS must not be blocked.

Authorizations:
apiKeyBasicAuth
path Parameters
domain_id
required
string
Example: example.com

Domain ID (integer) or fully qualified domain name

id
required
integer
Example: 98765

DNS record ID

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/domains/example.com/records/98765' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

email

Manage hosted e-mail accounts and settings

Get email service overview

Retrieves comprehensive overview of the user's email service including all email addresses (mailboxes and aliases), storage quota usage, and currently running mailbox import operations.

Access Requirements:

  • User must have email services enabled
  • Requires at least one email-enabled domain or setup-before-transfer domain

Response Data:

  • Complete list of mailboxes and aliases across all domains
  • Current storage usage in kilobytes and percentage
  • Storage quota limits
  • Active import operations with progress tracking
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/email' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "email_available": true,
  • "usage_kb": 512000,
  • "limit_kb": 2048000,
  • "usage_percent": 25,
  • "email_addresses": [
    ],
  • "running_imports": [
    ]
}

List email-enabled domains

Returns a list of all domains that have email services activated for the current user. This includes both external domains (with proper MX records) and lima-city hosted domains.

Domain Types:

  • Hosted domains: Domains managed within lima-city infrastructure
  • External domains: Domains with MX records pointing to mail.lima-city.de

Access Requirements:

  • User must have email services enabled
  • External email domains require premium subscription

Domain Format:

  • Both ASCII (IDNA-encoded) and Unicode (human-readable) formats provided
  • Sorted by domain parts for consistent ordering
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/email_domains' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "email_available": true,
  • "email_domains": [
    ]
}

Check email domain status

Verifies the configuration status of email services for a specific domain. This endpoint can be used to confirm that email services are properly configured and operational.

Status Information:

  • Returns 'ok' when domain email configuration is valid
  • Can be used to verify domain setup before creating mailboxes

Domain Format:

  • Use fully qualified domain name (FQDN)
  • Both ASCII and Unicode domain names supported
Authorizations:
apiKeyBasicAuth
path Parameters
domain_fqdn
required
string
Example: example.com

Fully qualified domain name (e.g., 'example.com' or 'exämple.de')

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/email_domains/example.com/status' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Activate email services for a domain

Enables email hosting services for an external domain by creating the necessary mail transport configuration. This operation requires proper DNS configuration and premium subscription.

Prerequisites:

  • Domain must have valid MX record pointing to mail.lima-city.de
  • User must have premium subscription
  • External email feature must be enabled for the user account
  • Domain must be in the list of potential (eligible) domains

DNS Requirements:

  • MX record must point to: mail.lima-city.de
  • Only one MX record allowed (no fallback MX servers)
  • DNS changes must be propagated before activation

Validation Rules:

  • Domain MX record is checked via DNS query
  • Domain must be owned or managed by the user
  • Domain cannot already have email services activated

Success Response:

  • Redirects to email overview
  • Success message (German): "Die E-Mail-Dienste wurden für {domain} aktiviert." (Email services have been activated for {domain})

Error Messages:

  • "Ungültige Domain-Konfiguration für {domain}." (Invalid domain configuration for {domain}) - Returned when:
    • MX record does not point to mail.lima-city.de
    • Multiple MX records exist
    • Domain is not in potential domains list
    • DNS resolution fails
Authorizations:
apiKeyBasicAuth
path Parameters
domain_fqdn
required
string
Example: example.com

Fully qualified domain name to activate email services for (e.g., 'example.com')

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/email/example.com/activate' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "error": "Ungültige Domain-Konfiguration für example.com."
}

Create a mailbox

Authorizations:
apiKeyBasicAuth
Request Body schema: application/json

mailbox object

required
object (mailboxes_mailbox)
login
required
string

The local part of the mailbox

domain
required
string

Enables relaxed HELO mail checks. Accepts lots of spam.

password
required
string <password>

The mailbox password

greylisting
boolean

Enables greylisting

Responses

Request samples

Content type
application/json
{
  • "mailbox": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Show mailbox

Authorizations:
apiKeyBasicAuth
path Parameters
mailboxId
required
string

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/mailboxes/example' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "id": 123,
  • "type": "mailbox",
  • "email": "info@example.com",
  • "local_part": "info",
  • "domain": "example.com",
  • "access_denied": false,
  • "destinations": [
    ]
}

Update mailbox settings

Authorizations:
apiKeyBasicAuth
path Parameters
mailboxId
required
string
Request Body schema: application/json

The new mailbox settings

required
object (mailboxesmailboxId_mailbox)
greylisting
boolean

Enables greylisting

relaxed_helo
boolean

Enables relaxed HELO mail checks. Accepts lots of spam.

password_api_enabled
boolean

Enables the user to change his passsword

Responses

Request samples

Content type
application/json
{
  • "mailbox": {
    }
}

Response samples

Content type
application/json
{
  • "id": 123,
  • "type": "mailbox",
  • "email": "info@example.com",
  • "local_part": "info",
  • "domain": "example.com",
  • "access_denied": false,
  • "destinations": [
    ]
}

Delete the mailbox

Authorizations:
apiKeyBasicAuth
path Parameters
mailboxId
required
string

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/mailboxes/example' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update mailbox password

Authorizations:
apiKeyBasicAuth
path Parameters
mailboxId
required
string
Request Body schema: application/json

The new mailbox password

required
object (mailboxesmailboxIdpassword_mailbox)
password
string <password>

The new password

Responses

Request samples

Content type
application/json
{
  • "mailbox": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Create an email alias

Authorizations:
apiKeyBasicAuth
Request Body schema: application/json

alias object

required
object (aliases_alias)
local_part
required
string

The local part of the mailbox

domain
required
string

Enables relaxed HELO mail checks. Accepts lots of spam.

type
required
string

"internal" (a mailbox) or "external" (e-mail addresses)

mailbox
string

Only for type "internal": A mailbox id

email_address
string

Only for type "external": A list of email addresses delimited by newlines

Responses

Request samples

Content type
application/json
{
  • "alias": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Delete the alias

Authorizations:
apiKeyBasicAuth
path Parameters
aliasId
required
string

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/aliases/example' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

php

Read and manipulate PHP hosting settings

List PHP mails

List PHP mails sent from your applications with pagination support. Shows email delivery status, sending limits, and delivery statistics.

Sending States:

  • active: Mail sending is enabled
  • paused: Mail sending is temporarily paused
  • blocked: Mail sending is blocked (limit = 0 or account restricted)
Authorizations:
apiKeyBasicAuth
query Parameters
page
integer >= 1
Default: 1

Page number for pagination (default: 1)

filter
string
Value: "failed"

Filter mails by delivery status. Use 'failed' to show only emails with delivery failures.

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/php_mails?page=1&filter=failed' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "sending_state": "active",
  • "sent_today": 15,
  • "sent_yesterday": 23,
  • "queued_mails": 3,
  • "current_limit": 500,
  • "max_limit": 500,
  • "delivery_percentage": 95.5,
  • "emails": [
    ],
  • "pagination": {
    }
}

Show a single PHP mail

Retrieves the complete email body for a single PHP mail message. The response contains the raw email including headers (From, To, Subject, etc.) and the message body in plain text format.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

Unique identifier of the PHP mail message to retrieve

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/php_mails/12345' \
  --user 'api:YOUR_API_KEY'

Empty mail queue

Deletes all unsent (queued but not yet delivered) emails from the user's queue. Delivered or failed emails are not affected.

Note: This operation cannot be undone. Only emails with state: 'queued' or state: 'created' will be deleted.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/php_mails/empty_queue' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Show PHP mail limit

Shows the current PHP mail sending limit for the authenticated user. The limit represents the maximum number of emails that can be sent per day.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/php_mails/limit' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "limit": 100
}

Update PHP mail limit

Updates the user's PHP mail sending limit.

Validation Rules:

  • Limit must be a positive integer (> 0)
  • Free accounts: maximum limit is 50 emails/day
  • Premium accounts: maximum limit is based on subscription (typically 500 emails/day)
  • Cannot update limit if mail sending is blocked (current limit = 0)

Error Responses:

  • limit over contract maximum: "ist über dem vertraglich erlaubten Limit von X"
  • Mail sending blocked: "kann derzeit nicht geändert werden, Versand ist gesperrt"
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

The new mail limit value

required
object
limit
required
integer >= 1

New PHP mail sending limit to set (must be positive integer)

Responses

Request samples

Content type
application/json
{
  • "phpmail_limit": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

List PHP versions

List available php versions and see the account default

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/php_version' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
[
  • {
    }
]

Updates the active PHP version

Authorizations:
apiKeyBasicAuth
Request Body schema: application/json

Inventory item to add

version
required
string

Responses

Request samples

Content type
application/json
{
  • "version": "7.1"
}

wordpress

WordPress management API. Show and manage WordPress installations, plugins and themes.

List WordPress installations

Retrieves all WordPress installations in the user's webspace. Each installation includes configuration details, associated domains, and staging environment status if applicable.

The system automatically detects WordPress installations by scanning for wp-config.php files and extracts configuration data.

Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/wordpress' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
[
  • {
    }
]

Show WordPress installation details

Retrieves detailed information about a specific WordPress installation including configuration, associated domains, and staging environment status.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID (numeric database ID)

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/wordpress/12345' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "id": 12345,
  • "path": "mein-wordpress",
  • "link_id": "12345",
  • "wordpress": {
    },
  • "websites": []
}

List WordPress plugins, themes, and updates

Retrieves comprehensive information about all installed plugins and themes, including their versions, activation status, and available updates. Also includes WordPress core update information.

Component Status:

  • active: Component is currently active
  • inactive: Component is installed but not active

Update Status:

  • none: No update available
  • available: Update is available (update_version field will be present)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/wordpress/12345/components' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "components": {
    }
}

Update WordPress plugins, themes, or languages

Queues a WP-CLI task to update specified WordPress components. Only one type of component (plugins, themes, or languages) can be updated per request.

Process:

  1. Request queues a background task
  2. Response includes a task_id
  3. Use /wordpress_tasks/{task_id} to check status and results

Validation Rules:

  • Only one of plugins, themes, or languages can be specified
  • Component slugs must be valid installed components
  • Task execution is asynchronous

Error Messages:

  • action_name: "muss ausgefüllt werden" (must be filled in) - action_name is missing
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Request Body schema: application/json
required

Components to update (only one type per request)

plugins
Array of strings

Array of plugin slugs to perform action on

themes
Array of strings

Array of theme slugs to perform action on

languages
Array of strings

Array of language codes to perform action on

Responses

Request samples

Content type
application/json
Example
{
  • "plugins": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

Activate WordPress plugins or themes

Queues a WP-CLI task to activate specified plugins or themes. For themes, only one can be active at a time (activating a theme deactivates the current one).

Process:

  1. Request queues a background task
  2. Response includes a task_id
  3. Use /wordpress_tasks/{task_id} to check status and results

Validation Rules:

  • Only one of plugins or themes can be specified
  • Component slugs must be valid installed components
  • Task execution is asynchronous

Error Messages:

  • action_name: "muss ausgefüllt werden" (must be filled in) - action_name is missing
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Request Body schema: application/json
required

Components to activate

plugins
Array of strings

Array of plugin slugs to perform action on

themes
Array of strings

Array of theme slugs to perform action on

languages
Array of strings

Array of language codes to perform action on

Responses

Request samples

Content type
application/json
{
  • "plugins": [
    ],
  • "themes": [
    ],
  • "languages": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

Deactivate WordPress plugins or themes

Queues a WP-CLI task to deactivate specified plugins. Note: Themes cannot be deactivated, only switched to another theme using the activate action.

Process:

  1. Request queues a background task
  2. Response includes a task_id
  3. Use /wordpress_tasks/{task_id} to check status and results

Validation Rules:

  • Only plugins can be deactivated (not themes)
  • Plugin slugs must be valid installed plugins
  • Task execution is asynchronous

Error Messages:

  • action_name: "muss ausgefüllt werden" (must be filled in) - action_name is missing
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Request Body schema: application/json
required

Plugins to deactivate

plugins
Array of strings

Array of plugin slugs to perform action on

themes
Array of strings

Array of theme slugs to perform action on

languages
Array of strings

Array of language codes to perform action on

Responses

Request samples

Content type
application/json
{
  • "plugins": [
    ],
  • "themes": [
    ],
  • "languages": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

Uninstall WordPress plugins or themes

Queues a WP-CLI task to uninstall (delete) specified plugins or themes. This is a destructive operation that removes the component files and data.

Warning: Uninstalling a plugin will:

  1. Deactivate the plugin (if active)
  2. Run the plugin's uninstall routine (if defined)
  3. Delete all plugin files

Process:

  1. Request queues a background task
  2. Response includes a task_id
  3. Use /wordpress_tasks/{task_id} to check status and results

Validation Rules:

  • Only one of plugins or themes can be specified
  • Component slugs must be valid installed components
  • Task execution is asynchronous
  • Cannot uninstall currently active themes

Error Messages:

  • action_name: "muss ausgefüllt werden" (must be filled in) - action_name is missing
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Request Body schema: application/json
required

Components to uninstall

plugins
Array of strings

Array of plugin slugs to perform action on

themes
Array of strings

Array of theme slugs to perform action on

languages
Array of strings

Array of language codes to perform action on

Responses

Request samples

Content type
application/json
{
  • "plugins": [
    ],
  • "themes": [
    ],
  • "languages": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

Update WordPress core

Queues a WP-CLI task to update WordPress core to the latest available version. This updates the WordPress installation files while preserving themes, plugins, and content.

Process:

  1. Request queues a background task
  2. Response includes a task_id
  3. Use /wordpress_tasks/{task_id} to check status and results

Important: Always backup before updating WordPress core.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/wordpress/12345/update' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok",
  • "object": {
    }
}

List security issues and malicious files

Retrieves a list of files flagged as malicious or containing security vulnerabilities in this WordPress installation. These files have been detected by security scans.

Note: This endpoint returns HTML/view data rather than JSON API format.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/wordpress/12345/issues' \
  --user 'api:YOUR_API_KEY'

Upload WordPress archive for import

Uploads a WordPress backup archive (Duplicator .zip or All-in-One WP Migration .wpress) for import. The archive is validated and metadata is extracted.

Supported Formats:

  • Duplicator plugin archives (.zip)
  • All-in-One WP Migration plugin archives (.wpress)

Process:

  1. Upload archive file
  2. System validates archive structure
  3. Extracts WordPress version, site name, and original URL
  4. Returns import ID for configuration
  5. Use /wordpress/import/{id} endpoints to configure and start import

Validation:

  • Archive must be valid WordPress backup format
  • Archive must contain recognizable WordPress structure
  • Maximum file size depends on server configuration

Error Messages:

  • "Das Archiv ist ungültig" (The archive is invalid) - Archive format not recognized or corrupted
Authorizations:
apiKeyBasicAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

WordPress backup archive (.zip or .wpress)

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/wordpress/upload' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "success",
  • "id": 12345,
  • "message": "Das Archiv ist ungültig"
}

Show WordPress import details

Retrieves details about an uploaded WordPress import including extracted metadata, processing state, and configuration options.

Import States:

  • uploaded: Archive uploaded and validated, ready to configure
  • running: Import is currently in progress
  • successful: Import completed successfully
  • failed: Import failed (check logs for details)

Note: This endpoint returns HTML/view data for the import configuration form rather than JSON API format.

Authorizations:
apiKeyBasicAuth
path Parameters
importId
required
integer
Example: 12345

Import record ID from upload response

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/wordpress/import/12345' \
  --user 'api:YOUR_API_KEY'

Start WordPress import

Configures and starts the WordPress import process. The uploaded archive is imported into the selected website directory and connected to the selected website.

Process:

  • Validates the selected directory and website
  • Imports the WordPress files and database contents
  • Applies the selected import options

Validation Rules:

  • directory: Required, must not exist unless overwrite_existing_installation is '1'
  • vhost_id: Required, must exist, must not be wildcard domain

Error Messages:

  • vhost_id: "existiert nicht" (does not exist) - Website not found
  • vhost_id: "Haupt-Domain darf keine Wildcard-Domain sein" (Main domain must not be wildcard)
  • overwrite_existing_installation: "das Verzeichnis existiert bereits, bitte bestätige das Überschreiben des Verzeichnis" (directory exists, please confirm overwrite)
Authorizations:
apiKeyBasicAuth
path Parameters
importId
required
integer
Example: 12345

Import record ID from upload response

Request Body schema: application/json
required
directory
required
string

Target directory for WordPress installation. Will be normalized using Pathname.cleanpath

vhost_id
required
integer

Virtual host ID to associate with this installation. Must not be a wildcard domain

create_cronjob
string
Enum: "0" "1"

Whether to create a system cron job for wp-cron.php (recommended). Use '1' to enable

install_core_updates
string
Enum: "0" "1"

Whether to install WordPress core updates after import. Use '1' to enable

use_memcached_object_cache
string
Enum: "0" "1"

Whether to enable Memcached object caching. Use '1' to enable

overwrite_existing_installation
string
Enum: "0" "1"

Whether to overwrite if directory already exists. Use '1' to confirm overwrite

Responses

Request samples

Content type
application/json
{
  • "directory": "my-imported-site",
  • "vhost_id": 54321,
  • "create_cronjob": "1",
  • "install_core_updates": "1",
  • "use_memcached_object_cache": "1",
  • "overwrite_existing_installation": "0"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Show WordPress task status

Retrieves the status and results of a WordPress CLI task. Tasks are created by various WordPress operations (updates, activations, etc.) and execute asynchronously.

Task Statuses:

  • created: Task has been queued but not yet started
  • running: Task is currently executing
  • refreshing: Task is refreshing cached data
  • success: Task completed successfully
  • failed: Task failed (check output for error details)

Note: This endpoint returns HTML/view data rather than JSON API format.

Authorizations:
apiKeyBasicAuth
path Parameters
taskId
required
string
Example: a1b2c3d4e5

Task ID from task creation response (10 character alphanumeric)

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/wordpress_tasks/a1b2c3d4e5' \
  --user 'api:YOUR_API_KEY'

wordpress-staging

WordPress staging API. Create and drop staging copies of your WordPress installation and go live if you are happy with the changes.

Show WordPress staging environment

Retrieves information about the staging environment for this WordPress installation. Returns staging details if a staging environment exists, or null if no staging has been created.

Staging Environment: A staging environment is a complete copy of your WordPress installation in a separate directory with its own database. It allows you to safely test changes before deploying to production.

Staging Workflow:

  1. Create staging with POST /wordpress/{id}/start_staging
  2. Test changes on staging site at staging_url
  3. Either:
    • Deploy changes to production with POST /wordpress/{id}/go_live, OR
    • Delete staging with POST /wordpress/{id}/drop_staging
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/wordpress/12345/staging' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "staging": { }
}

Create WordPress staging environment

Creates a complete copy of the WordPress installation for safe testing. The process copies the site's files and database contents, then configures a separate staging environment.

What Happens:

  • Creates an isolated staging copy of the WordPress installation
  • Configures a staging hostname
  • Optionally runs core and plugin updates on the staging copy

Staging Hostname Generation: The staging hostname is generated automatically from the original website hostname.

Validation Rules:

  • No staging environment can already exist for this installation
  • Must have a valid WordPress configuration
  • Must be able to generate a unique staging hostname

Error Messages:

  • base: "kann keine verbundene Webseite finden" (cannot find connected website)
  • base: "kann keinen freien Staging-Hostnamen finden" (cannot find free staging hostname)
  • base: "hat keine Konfiguration" (has no configuration)
  • base: "ist bereits mit einer Staging-Umgebung verbunden" (already connected to staging environment)
  • base: "die Datenbank-Konfiguration ist ungültig" (database configuration is invalid)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Request Body schema: application/json
optional

Staging configuration options

object
update
string
Enum: "0" "1"

Whether to run core and plugin updates on the staging copy after creation. Use '1' to enable

Responses

Request samples

Content type
application/json
{
  • "staging": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Deploy staging to production (go live)

Replaces the production WordPress installation with the staging version. This is a destructive operation that swaps the staging and production environments.

Warning: This operation is destructive and cannot be undone. Always backup before going live.

After Go-Live:

  • The staging environment becomes the new production environment
  • You can create a new staging environment from the new production

Validation Rules:

  • Staging environment must exist
  • Staging data must be valid and usable
  • Live path and staging path must be valid

Error Messages:

  • base: "hat keine aktive Staging-Umgebung" (has no active staging environment)
  • base: "die Staging-Datenbank ist ungültig" (staging database is invalid)
  • base: "der Live-Pfad (path) ist ungültig" (live path is invalid)
  • base: "der Staging-Pfad (path) ist ungültig" (staging path is invalid)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/wordpress/12345/go_live' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Delete staging environment

Permanently deletes the staging environment. This is a destructive operation that cannot be undone.

Warning: This operation permanently deletes the staging copy and its data.

Validation Rules:

  • Staging environment must exist
  • Live path and staging path must be valid

Error Messages:

  • base: "hat keine aktive Staging-Umgebung" (has no active staging environment)
  • base: "die Staging-Datenbank ist ungültig" (staging database is invalid)
  • base: "der Live-Pfad (path) ist ungültig" (live path is invalid)
  • base: "der Staging-Pfad (path) ist ungültig" (staging path is invalid)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
integer
Example: 12345

WordPress installation ID

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/wordpress/12345/drop_staging' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

cloud

Manage virtual machines (Cloud VPS and vServer). Control power state, manage resources, create snapshots, and monitor performance.

Get cloud account status

Retrieve the status and configuration of the user's cloud account. Returns cloud account information including verification requirements if the account exists, or an empty object if cloud services have not been activated.

Cloud Account Overview: lima-city's cloud services allow users to create and manage virtual machines (VPS), with flexible billing options and resource limits. Users must activate cloud services before they can create cloud resources.

Response Details:

  • If cloud account exists: Returns account status with verification flags
  • If no cloud account: Returns cloud_account: {}

Verification Requirements: Depending on account state and payment method, additional verification may be required. Check sms_verification_required, payment_required, and payment_method_verification_required in the response before creating cloud resources.

Resource Limits: When cloud services are activated, default limits are set:

  • Memory: 64 GB total across all VMs
  • vCores: 6 cores total across all VMs
  • Instances: 3 VMs maximum
  • Storage: 500 GB total SSD storage
  • Spending limit: €100/month (prepaid only)

Authorization Requirements:

  • User must be authenticated
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/cloud_account' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
Example
{
  • "cloud_account": {
    }
}

Activate cloud services

Activate lima-city cloud services for the authenticated user. This creates a cloud account and sets initial resource limits, enabling the user to create virtual machines and other cloud resources.

Activation Process: When activating cloud services, the user must:

  1. Choose a billing mode (prepaid, credit card, or direct debit)
  2. Accept the Terms of Service
  3. Optionally provide a billing address for invoices

Billing Modes:

  1. Prepaid (payment_method: 'prepaid'):

    • Pay in advance using account credit
    • Default spending limit: €100/month
    • No payment_method_id required
    • User must maintain sufficient account balance
    • Charges are deducted from prepaid balance

  2. Credit Card (payment_method: 'credit_card'):

    • Automatic monthly billing via credit card
    • No spending limit (unless billing_handle_id provided)
    • Requires payment_method_id (ID of stored credit card)
    • First-time users may need to make initial payment (see payment_required flag)
    • Monthly invoices charged automatically

  3. Direct Debit (payment_method: 'direct_debit'):

    • Automatic monthly billing via SEPA direct debit
    • No spending limit (unless billing_handle_id provided)
    • Requires payment_method_id (ID of SEPA mandate)
    • Direct debit must be verified before use (see payment_method_verification_required flag)
    • Monthly invoices charged via bank transfer

Resource Limits: Upon activation, the following default limits are set:

  • Memory: 64 GB RAM total across all VMs
  • vCores: 6 CPU cores total across all VMs
  • Instances: Maximum 3 virtual machines
  • Storage: 500 GB SSD storage total
  • Spending limit: €100/month (prepaid only, removed if billing_handle_id provided)

Reactivation: If the user previously had cloud services and is reactivating:

  • Existing cloud account is updated with new billing settings
  • Resource limits are reset to defaults
  • Previous cloud resources may still exist

Validation Rules:

  • payment_method: Required, must be 'prepaid', 'credit_card', or 'direct_debit'
  • payment_method_id: Required unless payment_method is 'prepaid'
  • billing_handle_id: Optional, must be valid user handle if provided
  • tos_accepted: Required, must be true

Error Messages:

  • payment_method_id: "ist ungültig" (is invalid) - Payment method ID does not exist or is not active
  • billing_handle_id: "ist ungültig" (is invalid) - Billing handle ID does not exist or does not belong to user
  • tos_accepted: "muss ausgefüllt werden" (must be filled in) - Terms of Service not accepted
  • payment_method: "muss ausgefüllt werden" (must be filled in) - Payment method not specified
  • payment_method: "ist nicht in der Liste enthalten" (is not in the list) - Invalid payment method value

Authorization Requirements:

  • User must be authenticated
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required

Cloud account activation parameters

required
object

Cloud account activation parameters

payment_method
required
string
Enum: "prepaid" "credit_card" "direct_debit"

Billing mode for cloud services. prepaid: Pay in advance with account credit (default spending limit: €100/month). credit_card: Automatic monthly billing via credit card (no spending limit). direct_debit: Automatic monthly billing via SEPA direct debit (no spending limit). When selecting credit_card or direct_debit, payment_method_id must be provided.

payment_method_id
integer

ID of the payment method to use for automatic billing. Required unless payment_method is 'prepaid'. Must reference an active payment method belonging to the user. For credit cards, ID from user's stored payment methods. For direct debit, ID from user's SEPA mandates.

billing_handle_id
integer

ID of the billing address (handle) to use for invoices. Optional. If provided, must reference a valid handle belonging to the user. When specified, removes spending limit for postpaid accounts.

tos_accepted
required
boolean

User must accept Terms of Service. Must be true to activate cloud services.

Responses

Request samples

Content type
application/json
Example
{
  • "cloud_account": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

List placement groups

List all placement groups owned by the user with their current capacity and status.

What are Placement Groups?

Placement groups enable VM anti-affinity - ensuring that virtual machines in the same group are placed on different physical hypervisors. This provides high availability and fault tolerance by preventing multiple VMs from being affected by a single hardware failure.

Use Cases:

  • High Availability: Deploy multiple web servers in the same group to ensure at least one remains operational during hardware maintenance or failures
  • Fault Tolerance: Distribute database replicas across different physical hosts
  • Load Balancing: Ensure backend services are spread across different hardware for better resilience

Features:

  • View all placement groups with real-time capacity information
  • Each group shows current VM count and remaining capacity
  • Maximum 5 virtual machines per placement group
  • Groups include associated virtual machines in the response

Capacity Management:

  • Each placement group has a fixed maximum size of 5 VMs
  • The full field indicates if the group has reached capacity
  • The remaining field shows how many more VMs can be added
  • Attempting to add VMs to a full group will fail with validation error

Authorization:

  • Requires authenticated user account
  • No special cloud or premium subscription required to view placement groups
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/placement_groups' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "placement_groups": [
    ]
}

List all virtual machines

List all virtual machines (Cloud VPS and vServer) owned by the user with current status information.

Features:

  • Real-time status for operational VMs (running/stopped, CPU usage, uptime)
  • Provisioning status for non-operational VMs (lifecycle state, progress)
  • Network traffic statistics for current billing period
  • IP address assignments (IPv4/IPv6)
  • Snapshot usage information
  • Contract information for vServer type VMs

Authorization:

  • Requires cloud account to be enabled and verified
Authorizations:
apiKeyBasicAuth

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/virtual_machines' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "virtual_machines": [
    ]
}

Create a new virtual machine

Create a new virtual machine (Cloud VPS or vServer) from an OS template, ISO, or snapshot.

VM Creation Methods:

  • Image (template_type='image'): Automated OS installation with SSH keys (Ubuntu, Debian, etc.)
  • ISO (template_type='iso'): Manual installation from ISO file
  • Snapshot (template_type='snapshot'): Restore from existing VM snapshot

Process:

  1. VM is created in 'created' state
  2. IP addresses are assigned based on ip_assignment parameter
  3. VM enters 'provisioning' state
  4. After provisioning completes, VM becomes 'operational'
  5. User can access VM via SSH (images) or console (ISO)

Resource Requirements:

  • Must have enabled cloud account with sufficient limits
  • Must have sufficient account balance (prepaid accounts)
  • Selected VM package must be available
  • For snapshots: VM package disk must be >= snapshot disk size

Validation Rules:

  • Hostname is required and must be valid FQDN format
  • For image type: SSH keys are mandatory (German: 'es muss mindestens ein SSH-Key ausgewählt werden')
  • For snapshot type: snapshot_id must reference a completed snapshot
  • template_type determines whether template_id or snapshot_id is required
  • Root password must meet strength requirements if set_root_password='1'

Error Messages:

  • 'kein gültiges Modell!' (no valid model) - invalid virtual_machine_model_id
  • 'kann ohne Cloud-Account nicht erstellt werden' (cannot be created without cloud account)
  • 'überschreitet das aktuelle Limit für VMs' (exceeds current VM limit)
  • 'kann derzeit nicht gestartet werden, keine freien Ressourcen' (cannot be started, no free resources)
  • 'ist zu klein für den ausgewählten Snapshot' (is too small for the selected snapshot)

Authorization:

  • Requires enabled cloud account
  • SMS verification must be completed
  • Payment method verification must be completed (if required)
Authorizations:
apiKeyBasicAuth
Request Body schema: application/json
required
required
object

Virtual machine creation parameters. Either template_id (for image/iso) or snapshot_id (for snapshot) is required based on template_type

hostname
required
string

Hostname for the virtual machine. Must be valid FQDN or will default to {uid}.trafficplex.cloud

virtual_machine_model_id
required
integer

ID of the VM package/model to use

template_type
required
string
Enum: "image" "iso" "snapshot"

Type of installation source

template_id
integer

ID of the template to use (required if template_type is 'image' or 'iso')

snapshot_id
integer

ID of the snapshot to restore from (required if template_type is 'snapshot')

ip_assignment
required
string
Enum: "ipv4" "ipv6" "dual-stack"

IP address assignment type

ssh_key_ids
Array of integers

Array of SSH key IDs to install (required for image template_type). German error: 'es muss mindestens ein SSH-Key ausgewählt werden' (at least one SSH key must be selected)

set_root_password
string
Enum: "0" "1"

Whether to set a custom root password ('1' for yes, '0' for no)

root_password
string

Root password (required if set_root_password is '1'). Must meet password strength requirements

placement_group_id
integer

Optional placement group ID for anti-affinity

Responses

Request samples

Content type
application/json
{
  • "usercp_create_vm": {
    }
}

Response samples

Content type
application/json
{
  • "virtual_machine": {
    }
}

Get virtual machine details

Get detailed information about a specific virtual machine including real-time status.

Operational VMs:

  • Current power state (running/stopped)
  • Real-time CPU usage percentage
  • Uptime in seconds
  • SSH host key fingerprints

Non-Operational VMs:

  • Lifecycle state (created, provisioning, rebuilding, destroying)
  • Restore/rebuild progress percentage
  • Time since provisioning started

Always Included:

  • Resource specifications (CPU, RAM, disk)
  • IP address assignments
  • Network traffic statistics
  • Snapshot usage
  • Contract information (vServer only)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/virtual_machines/vm8x7y9z' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "virtual_machine": {
    }
}

Update virtual machine settings

Update virtual machine hostname and/or automatic backup setting.

Hostname Update:

  • Updates the VM's hostname
  • Automatically updates reverse DNS (PTR) records for all IP addresses
  • Hostname validation: must be valid FQDN or defaults to {uid}.trafficplex.cloud

Backup Setting:

  • Enable or disable automatic backups
  • Applies to both Cloud VPS and vServer

Note: Both parameters are optional. Provide only the settings you want to update.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Request Body schema: application/json
required
hostname
string

New hostname for the VM. Updates reverse DNS automatically

backup
boolean

Enable or disable automatic backups

Responses

Request samples

Content type
application/json
{
  • "hostname": "newname.example.com",
  • "backup": true
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Destroy a Cloud VPS virtual machine

Permanently destroy a Cloud VPS virtual machine. This action is irreversible.

WARNING: This is a destructive operation that permanently deletes the VM and all its data.

Process:

  1. VM state changes to 'destroying'
  2. VM is powered off
  3. All disk data is securely wiped
  4. IP addresses are released
  5. VM state changes to 'destroyed'
  6. Billing charges are ended

Snapshots:

  • Optionally destroy all snapshots with destroy_snapshots='1'
  • If destroy_snapshots='0', snapshots remain available for creating new VMs

Restrictions:

  • Only available for Cloud VPS (hourly billing) type
  • Not available for vServer (contract-based) - use cancel endpoint instead

Authorization:

  • VM must be Cloud VPS type (not vServer)
  • User must own the VM
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Request Body schema: application/json
required
required
object
destroy_snapshots
string
Enum: "0" "1"

Whether to also destroy all snapshots ('1' for yes, '0' for no)

Responses

Request samples

Content type
application/json
{
  • "destroy_vm": {
    }
}

Response samples

Content type
application/json
{
  • "status": "Ok"
}

Start a virtual machine

Power on a stopped virtual machine.

Requirements:

  • VM must be in 'operational' lifecycle state
  • VM must be currently stopped

Process:

  1. Power on command sent to hypervisor
  2. VM boots from disk
  3. Status changes to 'running' within seconds
  4. Services start automatically

Note: This is a hard power-on, equivalent to pressing the power button on a physical machine.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/virtual_machines/vm8x7y9z/start' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Stop a virtual machine (hard stop)

Immediately power off a running virtual machine without graceful shutdown.

WARNING: This is equivalent to pulling the power cord. Data loss may occur if applications are writing to disk.

Requirements:

  • VM must be in 'operational' lifecycle state
  • VM must be currently running

Process:

  1. Immediate power off command sent to hypervisor
  2. VM stops immediately without OS shutdown procedures
  3. Status changes to 'stopped'

Recommendation: Use the shutdown endpoint for graceful shutdown when possible.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/virtual_machines/vm8x7y9z/stop' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Shutdown a virtual machine (graceful)

Gracefully shutdown a running virtual machine via ACPI signal.

Process:

  1. ACPI shutdown signal sent to VM
  2. Guest OS receives shutdown request
  3. OS performs clean shutdown (stops services, flushes buffers)
  4. VM powers off when OS shutdown completes
  5. Status changes to 'stopped'

Requirements:

  • VM must be in 'operational' lifecycle state
  • VM must be currently running
  • Guest OS must support ACPI (all modern OSes do)

Timeout: If guest OS doesn't respond within timeout period, VM may need to be stopped manually.

Note: This is the recommended way to stop a VM to prevent data corruption.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/virtual_machines/vm8x7y9z/shutdown' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Reset a virtual machine (hard reboot)

Immediately reset a running virtual machine without graceful shutdown.

WARNING: This is equivalent to pressing the reset button on a physical machine. Data loss may occur.

Requirements:

  • VM must be in 'operational' lifecycle state
  • VM must be currently running

Process:

  1. Immediate reset command sent to hypervisor
  2. VM hardware is reset without OS shutdown
  3. VM boots immediately
  4. Status remains 'running' (may briefly show as starting)

Use Cases:

  • VM is frozen or unresponsive
  • Emergency recovery when shutdown doesn't work
  • Testing kernel panic recovery

Recommendation: Use shutdown followed by start for graceful reboot when possible.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Responses

Request samples 

curl --request POST \
  --url 'https://www.lima-city.de/usercp/virtual_machines/vm8x7y9z/reset' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}

Rebuild virtual machine from new OS image

Rebuild the VM's disk from a fresh OS image template. This reinstalls the operating system.

WARNING: This is a destructive operation that erases all data on the VM's disk.

Process:

  1. VM state changes to 'rebuilding'
  2. Existing disk is wiped
  3. New OS image is deployed to disk
  4. Cloud-init configures SSH keys
  5. VM state changes to 'operational'
  6. VM is ready to boot

Requirements:

  • Must use 'image' type template (not ISO or snapshot)
  • Must provide at least one SSH key for access
  • VM will be stopped during rebuild

SSH Keys:

  • SSH keys are installed via cloud-init
  • Keys must belong to the user
  • At least one key is required (German: 'muss eine Liste von gültigen SSH-Key-IDs sein')

Validation Rules:

  • template_id must reference a valid enabled image template
  • ssh_key_ids must be an array of valid SSH key IDs
  • User must have access to the selected template

Error Messages:

  • 'ist kein gültiges Image' (is not a valid image) - invalid template_id or not an image type
  • 'muss eine Liste von gültigen SSH-Key-IDs sein' (must be a list of valid SSH key IDs)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Request Body schema: application/json
required
template_id
required
integer

ID of the image template to rebuild from

ssh_key_ids
required
Array of integers

Array of SSH key IDs to install. German error: 'muss eine Liste von gültigen SSH-Key-IDs sein' (must be a list of valid SSH key IDs)

Responses

Request samples

Content type
application/json
{
  • "template_id": 54322,
  • "ssh_key_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Resize virtual machine resources

Upgrade VM to a different package with more CPU, RAM, and optionally disk space.

Supported Changes:

  • Increase CPU cores
  • Increase RAM
  • Increase disk space (optional)

Restrictions:

  • Disk can only grow, never shrink (German: 'hat zu wenig Speicherplatz')
  • New package must have >= current disk size
  • If resize_disk='0', disk stays same size (only CPU/RAM upgrade)
  • If resize_disk='1', disk grows to match new package size
  • Cannot select same package unless disk needs resizing

Process:

  1. VM is stopped (if running)
  2. Resources are updated in hypervisor
  3. Disk is resized if resize_disk='1'
  4. Billing is updated to new package price
  5. VM can be started with new resources

Validation Rules:

  • virtual_machine_model_id must be a valid package for sale
  • New package must not shrink disk space
  • Must have sufficient account balance and limits
  • Cannot downgrade to same or smaller package

Error Messages:

  • 'kein gültiges Modell!' (no valid model) - invalid package ID
  • 'ist bereits das aktive Paket' (is already the active package) - trying to select current package
  • 'hat zu wenig Speicherplatz' (has too little storage) - new package disk < current disk
  • 'überschreitet das aktuelle Limit für VMs' (exceeds current VM limit)

Billing:

  • Current charges are ended
  • New charges start at new package rate
  • Prorated billing applies for Cloud VPS

Authorization:

  • Only available for Cloud VPS type (not vServer - vServers have fixed contracts)
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Request Body schema: application/json
required
required
object

Resize VM to a different package. Disk can only grow, not shrink. German error: 'hat zu wenig Speicherplatz' (has too little storage)

virtual_machine_model_id
required
integer

ID of the new VM model/package. Must have equal or greater disk space. German error: 'ist bereits das aktive Paket' (is already the active package)

resize_disk
string
Enum: "0" "1"

Whether to resize the disk to match new package ('1' for yes, '0' for no). If '0', only CPU and RAM are upgraded

Responses

Request samples

Content type
application/json
{
  • "usercp_resize_virtual_machine": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Change mounted ISO file

Mount a different ISO file in the VM's virtual CD-ROM drive.

Use Cases:

  • Boot from installation media
  • Run rescue/recovery tools
  • Install custom operating systems
  • Access diagnostic utilities

Process:

  1. Current ISO (if any) is unmounted
  2. New ISO is mounted in virtual CD-ROM
  3. VM can boot from ISO on next restart

Requirements:

  • template_id must reference an ISO type template
  • User must have access to the ISO template
  • VM does not need to be stopped

Boot Order:

  • VM will attempt to boot from mounted ISO before disk
  • Remove ISO (unmount) to boot from disk again

Validation:

  • template_id must exist and be visible to user
  • Must be ISO library type template (German: 'ist nicht gültig')

Error Messages:

  • 'ist nicht gültig' (is not valid) - invalid template_id or not an ISO type
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Request Body schema: application/json
required
required
object

Change the mounted ISO file. German error: 'ist nicht gültig' (is not valid)

template_id
required
integer

ID of the ISO template to mount

Responses

Request samples

Content type
application/json
{
  • "usercp_cloud_change_iso": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Change root password via guest agent

Change the root user password using QEMU guest agent.

Requirements:

  • VM must be running
  • QEMU guest agent must be installed in the guest OS
  • Guest agent must be active and communicating

How It Works:

  1. Password change command sent via QEMU guest agent
  2. Guest agent changes the root password inside the VM
  3. New password takes effect immediately

Guest Agent:

  • Most modern Linux distributions include qemu-guest-agent
  • Must be installed and running for this to work
  • If guest agent is not available, use console access to change password manually

Password Requirements:

  • Must meet password strength requirements
  • Typically: minimum length, mix of characters

Security Note: This method is more secure than using VNC console as credentials are not transmitted over VNC protocol.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Request Body schema: application/json
required
password
required
string

New root password. Must meet password strength requirements

Responses

Request samples

Content type
application/json
{
  • "password": "NewSecurePassword456!"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Restore VM from snapshot

Restore the VM's disk from a previously created snapshot.

WARNING: This is a destructive operation that replaces current disk data with snapshot data.

Process:

  1. VM state changes to 'rebuilding'
  2. Current disk data is discarded
  3. Snapshot data is restored to disk
  4. VM state changes to 'operational'
  5. VM can be started with restored data

Requirements:

  • VM must be in 'operational' state
  • No snapshot creation can be running
  • Snapshot must be in 'completed' state (usable)
  • Snapshot must belong to this VM

Validation Rules:

  • snapshot_id must reference a completed snapshot
  • VM cannot be rebuilding or destroying
  • No concurrent snapshot operations allowed

Error Messages:

  • 'ist kein gültiger Snapshot' (is not a valid snapshot) - invalid or unusable snapshot
  • 'die virtuelle Maschine ist in einem ungültigen Zustand' (VM is in an invalid state) - VM not operational
  • 'es wird derzeit ein Snapshot erstellt, dieser muss zuerst abgeschlossen werden' (a snapshot is currently being created, must complete first)

Note: VM will be stopped during restore if it's running.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Request Body schema: application/json
required
snapshot_id
required
integer

ID of the snapshot to restore from

Responses

Request samples

Content type
application/json
{
  • "snapshot_id": 67891
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Get vServer cancellation information

Get cancellation date information for a vServer contract.

Response Information:

  • next_cancellation_date: Earliest date when cancellation takes effect (respects contract period)
  • cancelled_at: Effective date if already cancelled, null otherwise
  • cancellation_received_date: When cancellation was submitted, null if not cancelled

Contract Period:

  • vServers have minimum contract periods (e.g., 1, 3, 6, or 12 months)
  • Cancellation takes effect at end of current contract period
  • After minimum period, contract continues month-to-month unless cancelled

Authorization:

  • Only available for vServer type VMs (not Cloud VPS)
  • Cloud VPS uses immediate destroy endpoint instead
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vs8x7y9z

Virtual machine UID (must be vServer type)

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/virtual_machines/vs8x7y9z/cancel' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "next_cancellation_date": "2023-04-30",
  • "cancelled_at": null,
  • "cancellation_received_date": null
}

Cancel vServer contract

Submit cancellation request for a vServer contract.

Process:

  1. Cancellation request is recorded with timestamp
  2. Cancellation becomes effective at end of current contract period
  3. VM continues running until effective date
  4. On effective date, VM is stopped and destroyed
  5. Billing ends on effective date
  6. User receives confirmation email

Requirements:

  • Must be vServer type (not Cloud VPS)
  • User password required for confirmation
  • Contract can only be cancelled once

Timeline:

  • Cancellation submitted: now
  • Effective date: next_cancellation_date (end of contract period)
  • VM accessible until: effective date

Validation:

  • Password must match user's account password
  • VM must be vServer type

Note: Cancellation cannot be undone. VM will be destroyed on the effective date.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vs8x7y9z

Virtual machine UID (must be vServer type)

Request Body schema: application/json
required
password
required
string

User's account password for confirmation

Responses

Request samples

Content type
application/json
{
  • "password": "MyAccountPassword"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Get performance metrics graph data

Get time-series performance metrics for the virtual machine.

Metrics Included:

  • CPU usage percentage (0-100)
  • Memory used in bytes
  • Network bytes in/out
  • Disk read/write bytes

Time Ranges:

  • Specify timeframe via query parameter
  • Common values: '1h', '6h', '1d', '1w', '1m'
  • Returns data points appropriate for the timeframe

Data Points:

  • Each point includes timestamp and all metrics
  • Some metrics may be null if not available
  • Timestamps are UTC ISO 8601 format

Use Cases:

  • Monitor resource usage over time
  • Identify performance bottlenecks
  • Track resource consumption patterns
  • Plan for scaling needs
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

query Parameters
timeframe
string
Example: timeframe=1d

Time range for metrics (e.g., '1h', '6h', '1d', '1w', '1m')

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/virtual_machines/vm8x7y9z/graph?timeframe=1d' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "graph": [
    ]
}

List snapshots for a virtual machine

List all snapshots for a specific virtual machine.

Snapshot States:

  • queued: Snapshot creation queued but not started
  • running: Snapshot is being created
  • completed: Snapshot is ready to use
  • failed: Snapshot creation failed
  • destroyed: Snapshot was deleted

Filtering:

  • Use filter=completed query parameter to show only usable snapshots
  • Without filter, shows all snapshots including failed and destroyed

Ordering: Snapshots are returned in descending order by ID (newest first)

Pagination: Supports pagination via page parameter

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

query Parameters
filter
string
Value: "completed"

Filter snapshots by state ('completed' shows only usable snapshots)

page
integer
Default: 1

Page number for pagination

Responses

Request samples 

curl --request GET \
  --url 'https://www.lima-city.de/usercp/virtual_machines/vm8x7y9z/snapshots?filter=completed&page=1' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
[]

Create a snapshot

Create a new snapshot of the virtual machine's current disk state.

Process:

  1. Snapshot is queued (state: 'queued')
  2. Snapshot creation starts (state: 'running')
  3. Disk data is copied to snapshot storage
  4. Snapshot completes (state: 'completed')
  5. Snapshot can be used for restore or new VM creation

Requirements:

  • VM must be in 'operational' state
  • No other snapshot can be running
  • Must not exceed included snapshot limit (or will be billed)

Snapshot Limits:

  • vServer: 2 included snapshots
  • Cloud VPS: 0 included (all snapshots are billed)
  • Additional snapshots incur charges

Naming:

  • Name is optional
  • If not provided, defaults to "Snapshot {ISO 8601 timestamp}"
  • Example: "Snapshot 2023-06-15T10:30:00Z"

Validation:

  • Cannot create snapshot if another is already running (German: 'Another snapshot is already running')
  • Cannot exceed maximum snapshots for vServer (German: 'You have reached the maximum number of snapshots for this virtual machine')

Use Cases:

  • Before major updates or changes
  • Regular backup strategy
  • Create point-in-time recovery points
  • Clone VMs from snapshots
Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

Request Body schema: application/json
optional
name
string

Optional custom name for the snapshot

Responses

Request samples

Content type
application/json
{
  • "name": "Before upgrade"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "id": 67891
}

Delete a snapshot

Delete a virtual machine snapshot.

Process:

  1. Snapshot is marked as destroyed (destroyed_at timestamp set)
  2. Billing charges for the snapshot are ended
  3. Snapshot data is removed from storage
  4. Snapshot cannot be restored after deletion

Requirements:

  • Snapshot must be in 'completed' or 'failed' state
  • Cannot delete running snapshots
  • Must be snapshot owner

Billing:

  • Charges end immediately upon deletion
  • No refunds for partial billing periods

Note: Deletion is permanent and cannot be undone. Ensure you don't need the snapshot before deleting.

Authorizations:
apiKeyBasicAuth
path Parameters
id
required
string
Example: vm8x7y9z

Virtual machine UID

snapshot_id
required
integer
Example: 67890

Snapshot ID

Responses

Request samples 

curl --request DELETE \
  --url 'https://www.lima-city.de/usercp/virtual_machines/vm8x7y9z/snapshots/67890' \
  --user 'api:YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "status": "ok"
}