REST API

The plugin exposes a small REST API under Modoboa's versioned API, mounted at:

/api/v2/virtualhosts/

All endpoints require an authenticated request with the appropriate Django model permissions on the VirtualHost model (in practice, a super administrator). Authenticate the same way you would for any other Modoboa v2 API call.

INFO

Virtual hosts are created by assigning a hostname to a domain through the domain API/forms, not through this API — there is no POST /virtualhosts/ create endpoint. See Virtual hosts.

Endpoints

Method	Path	Description
GET	/api/v2/virtualhosts/	List virtual hosts. Supports pagination, ordering (name, creation) and search (by name).
DELETE	/api/v2/virtualhosts/{id}/	Delete a virtual host (removes its Nginx config asynchronously).
GET	/api/v2/virtualhosts/for_domain/{domain_pk}/	Return the virtual host linked to a given domain.
POST	/api/v2/virtualhosts/{id}/retry_provisioning/	Re-run the provisioning chain. Valid only when the host is failed (else 409 Conflict).
POST	/api/v2/virtualhosts/{id}/set_state/	Enable/disable a host. Body: `{"enabled": true
GET	/api/v2/virtualhosts/{id}/theme/	Read the host's theme overrides.
PUT	/api/v2/virtualhosts/{id}/theme/	Update theme colors (partial payload — omitted fields are left untouched).
POST	/api/v2/virtualhosts/{id}/theme_logo/	Upload a logo. Multipart body: logo_type + image.
DELETE	/api/v2/virtualhosts/{id}/theme_logo/?logo_type=...	Clear a logo.

Virtual host representation

GET responses for a virtual host include:

Field	Description
pk	Identifier.
name	Hostname.
creation	Creation timestamp.
enabled	Whether the host is enabled.
domains	Linked domains (pk + name).
has_certificate	Whether a certificate exists on disk.
certificate_valid_until	Certificate expiry, if any.
provisioning_status	pending, ready or failed.
last_provisioning_error	Error message recorded on the last failure (empty otherwise).

Global settings

The plugin's global parameters (the ACME and Nginx settings from Configuration) are read and written through Modoboa's standard parameters API, the same way the Parameters panel does:

GET  /api/v2/parameters/virtualhosts/
PUT  /api/v2/parameters/virtualhosts/

Logo types

The logo_type value used by the theme_logo endpoints is one of:

• login — login page logo;
• menu — left-menu logo;
• creation_form — creation-form logo.

See Theming for what each logo controls.