Simple Hosting API

https://api.gandi.net/v5/simplehosting/

Simple Hosting API

Introduction

This section of our documentation will assist you in the management of Simple Hosting instances at Gandi.net through our REST API.

Documentation on our XML-RPC API can be found at https://doc.rpc.gandi.net

General information on Gandi's Simple Hosting services can be found in our public documentation at:
https://docs.gandi.net/en/simple_hosting

Simple Hosting applications list

https://api.gandi.net/v5/simplehosting/applications

get List Simple Hosting applications

This route lists the applications that can be installed on a Simple Hosting instance.

Request

Query String
  • Optional
    • databasestring
      Filters the list with the database they can use, with optional patterns.
      Example: mysql
      Example: pg*
    • languagestring
      Filters the list by the language they use, with optional patterns.
      Example: php
      Example: py*
    • namestring
      Filters the list by application name, with optional patterns.
      Example: nextcloud
      Example: mato*
      Example: *press
    • pageinteger

      Default: 1

      Minimum: 1

      Which result page to retrieve. If the number is greater than the last page, an empty list is returned.
    • per_pageinteger

      Minimum: 1

      How many items to display per page.
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
    • sort_bystring

      Default: "-created_at"

      Indicate the field used to sort the results. The field's name may start with - to reverse the order.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Headers
    • Total-Countinteger
      Total number of items.
    Optional
    • Linkstring
      Links to next and last page.
Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • namestring
      • name_labelstring
      • requirementsarray

        Of items of type:

        • object

          With the following properties:

          • databaseobject
            Database supported by the application

            With the following properties:

            • namestring
            • statusstring
            • versionstring
          • instance_minimum_sizestring
            Minimum required PaaS size for this application
          • languageobject
            Language used by the application

            With the following properties:

            • namestring
            • single_applicationboolean
              true if the application must be the only vhost of the instance
            • statusstring
            • versionstring

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Simple Hosting application information

https://api.gandi.net/v5/simplehosting/applications/{application_name}

get Application details

This route returns detailed information for a given application.

Request

URI Parameters
    • application_namestring
      Name of an application.

Responses

200

Body
  • application/json
    object

    With the following properties:

    • namestring
    • name_labelstring
    • requirementsarray

      Of items of type:

      • object

        With the following properties:

        • databaseobject
          Database supported by the application

          With the following properties:

          • namestring
          • statusstring
          • versionstring
        • instance_minimum_sizestring
          Minimum required PaaS size for this application
        • languageobject
          Language used by the application

          With the following properties:

          • namestring
          • single_applicationboolean
            true if the application must be the only vhost of the instance
          • statusstring
          • versionstring

Simple Hosting instances list

https://api.gandi.net/v5/simplehosting/instances

get List Simple Hosting instances

This route lists the instances the authenticated user has permission to access.

Request

Query String
  • Optional
    • fqdnstring
      Filters the list by vhost domain name, with optional patterns.
      The FQDN must be encoded in ASCII form (Punycode).
      Example: example.net
      Example: example.*
      Example: *example.com
    • namestring
      Filters the list by instance name, with optional patterns.
      Example: example
      Example: examp*
      Example: *mple
    • pageinteger

      Default: 1

      Minimum: 1

      Which result page to retrieve. If the number is greater than the last page, an empty list is returned.
    • per_pageinteger

      Minimum: 1

      How many items to display per page.
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
    • sizestring

      One of: "s", "s+", "m", "l", "xl", "xxl"

      Filters the list by instance size.
    • sort_bystring

      Default: "-created_at"

      Indicate the field used to sort the results. The field's name may start with - to reverse the order.
    • statusstring

      One of: "waiting_bill", "being_created", "active", "paused", "locked", "being_deleted"

      Filters the list by instance status.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Headers
    • Total-Countinteger
      Total number of items.
    Optional
    • Linkstring
      Links to next and last page.
Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • available_upgradeboolean
      • created_atdatetime
      • databaseobject

        With the following properties:

        • namestring
        • statusstring
        • versionstring
      • datacenterobject

        With the following properties:

        • codestring

          One of: "FR-SD3", "FR-SD5", "FR-SD6", "LU-BI1"

        • namestring
        • regionstring

          One of: "FR", "LU"

      • expire_atdatetime
      • idstring
        UUID
      • languageobject

        With the following properties:

        • namestring
        • single_applicationboolean
          true if the application must be the only vhost of the instance
        • statusstring
        • versionstring
      • namestring
      • sharing_spaceobject

        With the following properties:

        • idstring
          UUID
        Optional
        • namestring
      • sizestring

        One of: "s", "s+", "m", "l", "xl", "xxl"

      • snapshot_enabledboolean
      • statusstring

        One of: "waiting_bill", "being_created", "active", "paused", "locked", "being_deleted"

      • storageobject

        With the following properties:

        • additionalobject

          With the following properties:

          • unitstring

            One of: "GB"

          • valueinteger
        • baseobject

          With the following properties:

          • unitstring

            One of: "GB"

          • valueinteger
        • totalobject

          With the following properties:

          • unitstring

            One of: "GB"

          • valueinteger
      Optional
      • autorenewobject

        With the following properties:

        • durationinteger
        • duration_typestring

          One of: "m"

      • password_updated_atdatetime
        Last password update date. Only present if a password is set.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

post Create Simple Hosting instances

This route creates a new Simple Hosting instance Warning! This is not a free operation. Please ensure your prepaid account has enough credit.

Pay as an individual

To pay with your user organization (ie: yourself as an individual), just use the regular required parameters. The invoice will be edited with your personal information.

Pay as another organization

To pay using another organization, you'll need to perform the request with the organization's ID as the sharing_id query string parameter (see reference). The invoice will be edited using this organization's information.

For this to work, you need to:

  • have billing permissions on the organization

Request

Query String
  • Optional
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
    Optional
    • Dry-Runinteger
      If this header's value is 1 the request's parameters will only be checked; the operation will not actually be performed.
Body
  • application/json
    object

    With the following properties:

    Required
    • locationstring

      One of: "FR", "LU"

      Indicates where the instance will be created.
    • typeobject
      The database and language to use for the SimpleHosting instance.

      With the following properties:

      Required
      • databaseobject

        With the following properties:

        Required
        • namestring

          One of: "mysql", "pgsql"

          The database management system to use.
        Optional
        • versionstring
          The database version to use, defaulting on the recommended version if the field is missing.
      • languageobject

        With the following properties:

        Required
        • namestring

          One of: "php", "python", "nodejs", "ruby"

          The language interpreter to use
        Optional
        • versionstring
          The language version to use, if none given will chose the recommended version.
    Optional
    • authenticationobject

      If this field is absent, instance storage cannot be accessed through sftp and the advanced control panel will be unavailable until a password is set.

      Username and hostname to connect to will be available in instance details once created.

      With the following properties:

      Required
      • passwordstring
        The password for sftp, git and advanced control panel access. It can be provided in clear text or in unix crypt format using MD5, SHA-256 or SHA-512 as hash algorithm.
      Optional
      • keysarray
        IDs of SSH public keys registered through our SSH keys API.

        Of items of type:

        • string
          UUID
      • ssh_keysarray[ string ]
        SSH public keys for sftp and git access in OpenSSH format.
    • autorenewboolean
      If true, the instance will automatically be renewed upon expiration, ensure you have set up a payment method linked to your prepaid or that your prepaid has enough money.
    • durationinteger

      Default: 1

      Minimum: 1

      The duration your instance will be created for in duration_unit. If none given the instance will be created for a month.
    • duration_unitstring

      One of: "m"

      Default: "m"

      The unit to use for duration field, currently only months are supported (m)
    • namestring
      The name of the instance, if none is given a name will be generated.
    • sizestring

      One of: "s+", "m", "l", "xxl"

      Default: "m"

      The size of the instance
    • snapshot_enabledboolean

      Default: false

      If true, automatic snapshots will be enabled for this instance.

      Please note that a snapshot doesn't replace a proper backup.

    • storage_additional_sizeinteger

      Default: 0

      Minimum: 0

      Maximum: 1004

      Additional storage amount for the instance in GB
    • trialboolean

      Default: false

      If true, this will create a free trial instance for 10 days, given the fact you did not already used our SimpleHosting service in the past.
    • vhostsarray
      Creates the described vhosts on the instance on creation

      Of items of type:

      • object

        With the following properties:

        Required
        • fqdnstring
          FQDN of the vhost
        Optional
        • applicationobject
          An application to install on the vhost upon creation. The application list, parameters and language/database compatibility is available here

          With the following properties:

          Required
          • namestring
          Optional
          • parametersobject
        • https_strategystring

          One of: "HTTP_only", "allow_HTTP_and_HTTPS", "redirect_HTTP_to_HTTPS"

          Default: "allow_HTTP_and_HTTPS"

          The strategy to use for secure connection to the vhost.
        • linked_dns_zoneobject

          With the following properties:

          Optional
          • allow_alterationboolean

            Default: false

            If true we set the DNS records for the vhost, can only be set if related domain is managed by LiveDNS and you have the rights to manage the domain records.
          • allow_alteration_overrideboolean

            Default: false

            If true we will override an existing record for this vhost if one exists. Has no effect if zone_alter is false.
        • with_free_sslboolean

          Default: false

          If true, we will create a free certificate after the instance gets created.

Responses

200

Dry-Run response. You will get this response when you send your request. with a Dry-Run: 1 header.
Headers
  • Optional
    • Warningstring
      Warning message
Body
  • application/json
    object

    With the following properties:

    • statusstring

      One of: "success", "error"

      Response status.
    Optional
    • errorsarray
      A list of all the errors encountered during validation.

      Of items of type:

      • object

        With the following properties:

        • descriptionstring
          Error message.
        • locationstring

          One of: "header", "path", "querystring", "body"

          The field's location in the HTTP response.
        • namestring
          The xpath of the field.

202

Headers
    • Content-Locationstring
      Link to the created instance
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Simple Hosting instance information

https://api.gandi.net/v5/simplehosting/instances/{instance_id}

get Instance details

This route returns detailed information for a given instance.

Request

URI Parameters
    • instance_idstring
      UUID of an instance.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    object

    With the following properties:

    • access_informationobject

      With the following properties:

      • admin_urlstring
      • databaseobject

        With the following properties:

        • adminsarray

          Of items of type:

          • object

            With the following properties:

            • typestring

              One of: "phpMyAdmin", "phpPgAdmin", "Adminer"

            • urlstring
            Optional
            • usernamestring
        • hoststring
        Optional
        • portinteger
          In case the database listens to an inet-type socket this field will contain the port number used by the database
        • socketstring
          In the event this database listens to a UNIX-type socket this field will contain the path of the socket
      • deployarray

        Of items of type:

        • object

          With the following properties:

          • cliobject

            With the following properties:

            • initstring
          • gitobject

            With the following properties:

            • deploystring
            • remotestring
            • urlstring
          • sftpobject

            With the following properties:

            • directorystring
              Directory relative to the SFTP root where the vhost is located.
            • document_rootstring
              Directory relative to the SFTP root where the root of the exposed vhost is located.
            • serverstring
            • urlstring
          • vhostobject

            With the following properties:

            • fqdnstring
              FQDN linked to the vhost in ASCII (Punycode) format.
            • hrefstring
              Link to vhost details
      • userstring
    • available_upgradeboolean
    • consoleobject
      The emergency console is a serial-like console you can access via SSH.

      With the following properties:

      • enabledboolean
      • urlstring
    • created_atdatetime
    • databaseobject

      With the following properties:

      • namestring
      • statusstring
      • versionstring
    • datacenterobject

      With the following properties:

      • codestring

        One of: "FR-SD3", "FR-SD5", "FR-SD6", "LU-BI1"

      • namestring
      • regionstring

        One of: "FR", "LU"

    • expire_atdatetime
    • idstring
      UUID
    • is_trialboolean
    • languageobject

      With the following properties:

      • namestring
      • single_applicationboolean
        true if the application must be the only vhost of the instance
      • statusstring
      • versionstring
    • namestring
    • sharing_spaceobject

      With the following properties:

      • idstring
        UUID
      Optional
      • namestring
    • sizestring

      One of: "s", "s+", "m", "l", "xl", "xxl"

    • snapshot_enabledboolean
    • statusstring

      One of: "waiting_bill", "being_created", "active", "paused", "locked", "being_deleted"

    • storageobject

      With the following properties:

      • additionalobject

        With the following properties:

        • unitstring

          One of: "GB"

        • valueinteger
      • baseobject

        With the following properties:

        • unitstring

          One of: "GB"

        • valueinteger
      • totalobject

        With the following properties:

        • unitstring

          One of: "GB"

        • valueinteger
    • vhostsarray

      Of items of type:

      • object

        With the following properties:

        • fqdnstring
          FQDN linked to the vhost in ASCII (Punycode) format.
        • hrefstring
          Link to vhost details
    Optional
    • autorenewobject

      With the following properties:

      • durationinteger
      • duration_typestring

        One of: "m"

    • compatible_applicationsarray

      Of items of type:

      • object

        With the following properties:

        • namestring
        Optional
        • parametersobject
    • password_updated_atdatetime
      Last password update date. Only present if a password is set.
    • upgrade_toarray

      Of items of type:

      • object

        With the following properties:

        • namestring
        • statusstring
        • typestring
          Indicate whether the available upgrade is a database or a language upgrade.
        • versionstring

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

delete

This route deletes the given instance. This action can lead to a refund on your prepaid account if the instance is refundable.

Request

URI Parameters
    • instance_idstring
      UUID of an instance.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

204

Instance is deleted

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Simple Hosting instance actions

https://api.gandi.net/v5/simplehosting/instances/{instance_id}/action

post Perform an action on the instance

This route allows restarting, resetting the database password, and activating the instance console.

Request

URI Parameters
    • instance_idstring
      UUID of an instance.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Required
    • actionstring

      One of: "restart", "console", "reset_database_password"

Responses

202

Headers
    • Content-Locationstring
      Link to the instance on which the action is taken
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

204

An internal error has occurred and the action cannot be performed.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Simple Hosting instance vhost list and create

https://api.gandi.net/v5/simplehosting/instances/{instance_id}/vhosts

get List vhosts

This route is used to list vhosts of an instance.

Request

URI Parameters
    • instance_idstring
      UUID of an instance.
Query String
  • Optional
    • fqdnstring
      Filters the list by vhost domain name, with optional patterns.
      The FQDN must be encoded in ASCII form (Punycode).
      Example: example.net
      Example: example.*
      Example: *example.com
    • pageinteger

      Default: 1

      Minimum: 1

      Which result page to retrieve. If the number is greater than the last page, an empty list is returned.
    • per_pageinteger

      Minimum: 1

      How many items to display per page.
    • sort_bystring

      Default: "-created_at"

      Indicate the field used to sort the results. The field's name may start with - to reverse the order.
    • statusstring

      One of: "being_created", "running", "being_deleted", "locked", "waiting_ownership", "ownership_validated", "validation_failed"

      Filters the list by vhost status.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Headers
    • Total-Countinteger
      Total number of items.
    Optional
    • Linkstring
      Links to next and last page.
Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • created_atdatetime
      • fqdnstring
        FQDN linked to the vhost in ASCII (Punycode) format.
      • is_a_test_vhostboolean
        True if the vhost is intended for testing purposes only.
      • linked_dns_zoneobject
        This field contains information on the DNS zone the vhost is linked to.

        With the following properties:

        • allow_alterationboolean
          True if you authorized Gandi to modify your DNS zone so that your vhost points to our Simple Hosting public endpoints. If set to True and your DNS zone is managed by our liveDNS platform, you will not have to manually change your DNS configuration to validate your vhost ownership. Check last_checked_status to validate.
        • last_checked_statusstring

          One of: "altered", "livedns_conflict", "livedns_done", "livedns_error", "unknown"

          DNS zone validity when last checked
        Optional
        • last_checked_atdatetime
          Date of the last check for zone validity
      • statusstring

        One of: "being_created", "running", "being_deleted", "locked", "waiting_ownership", "ownership_validated", "validation_failed"

      Optional
      • applicationobject

        With the following properties:

        • namestring
        Optional
        • parametersobject
      • certificatesarray

        Of items of type:

        • object

          With the following properties:

          • hrefstring
          • idstring
          • pendingboolean
      • https_strategystring

        One of: "HTTP_only", "allow_HTTP_and_HTTPS", "redirect_HTTP_to_HTTPS"

        Describes the strategy used regarding secure connection to your vhost (HTTP/HTTPS). This field is only present if you have a certificate.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

post Create a new vhost

This route is used to create a vhost on an instance.

Request

URI Parameters
    • instance_idstring
      UUID of an instance.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Required
    • fqdnstring
      fqdn of the vhost.
    Optional
    • applicationobject

      With the following properties:

      Required
      • namestring
      Optional
      • parametersobject
    • linked_dns_zoneobject

      With the following properties:

      Required
      • allow_alterationboolean
        True if you authorized Gandi to modify your DNS zone so that your vhost points to our Simple Hosting public endpoints. If set to True and your DNS zone is managed by our liveDNS platform, you will not have to manually change your DNS configuration to validate your vhost ownership. Check last_checked_status to validate.
      Optional
      • allow_alteration_overrideboolean

        Default: false

        True to override your DNS zone if there already is a record on your vhost fqdn.

Responses

202

Headers
    • Content-Locationstring
      Link to the new vhost.
Body
  • application/json
    object

    With the following properties:

    • fqdnstring
      fqdn of the vhost.
    • https_strategystring

      One of: "HTTP_only", "allow_HTTP_and_HTTPS", "redirect_HTTP_to_HTTPS"

      Describes the strategy used regarding secure connection to your vhost (HTTP/HTTPS). This field is only present if you have a certificate.
    • linked_dns_zoneobject

      With the following properties:

      • allow_alterationboolean
        True if you authorized Gandi to modify your DNS zone so that your vhost points to our Simple Hosting public endpoints. If set to True and your DNS zone is managed by our liveDNS platform, you will not have to manually change your DNS configuration to validate your vhost ownership. Check last_checked_status to validate.
      • last_checked_statusstring

        One of: "altered", "livedns_conflict", "livedns_done", "livedns_error", "unknown"

        DNS zone validity when last checked
    • statusstring

      One of: "being_created", "running", "being_deleted", "locked", "waiting_ownership", "ownership_validated", "validation_failed"

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

422

The vhost already exist on the instance and the creation cannot be performed.

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Simple Hosting vhost information

https://api.gandi.net/v5/simplehosting/instances/{instance_id}/vhosts/{vhost_fqdn}

get Vhost details

This route returns the detailed information about the given vhost.

Request

URI Parameters
    • instance_idstring
      UUID of an instance.
    • vhost_fqdnstring
      fqdn of a vhost.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    object

    With the following properties:

    • created_atdatetime
    • fqdnstring
      FQDN linked to the vhost in ASCII (Punycode) format.
    • is_a_test_vhostboolean
      True if the vhost is intended for testing purposes only.
    • linked_dns_zoneobject
      This field contains information on the DNS zone the vhost is linked to.

      With the following properties:

      • allow_alterationboolean
        True if you authorized Gandi to modify your DNS zone so that your vhost points to our Simple Hosting public endpoints. If set to True and your DNS zone is managed by our liveDNS platform, you will not have to manually change your DNS configuration to validate your vhost ownership. Check last_checked_status to validate.
      • allow_alterationboolean
        True if you authorized Gandi to modify your DNS zone so that your vhost points to our Simple Hosting public endpoints. If set to True and your DNS zone is managed by our liveDNS platform, you will not have to manually change your DNS configuration to validate your vhost ownership. Check last_checked_status to validate.
      • cnamestring
        Canonical name of the web accelerator hosting your vhost. You need this if the vhost is not the apex (top level) of your zone
      • domainstring
        FQDN of the zone to which you need to apply the DNS records
      • ipv4string
        IPv4 pointing to the web accelerator hosting your vhost. You only need this if the vhost is at the root of your zone
      • ipv6string
        IPv6 pointing to the web accelerator hosting your vhost. You only need this if the vhost is at the root of your zone
      • is_alterableboolean
        True if the zone can be automatically managed by Simple Hosting
      • is_rootboolean
        True if the vhost is on the root of the zone. It means you have to add A and AAAA entries to your zone rather than a CNAME.
      • keystring
        The name associated with the entries to add to your zone, if the vhost is the root of your zone it should be @.
      • last_checked_statusstring

        One of: "altered", "livedns_conflict", "livedns_done", "livedns_error", "unknown"

        DNS zone validity when last checked
      • last_checked_statusstring

        One of: "altered", "livedns_conflict", "livedns_done", "livedns_error", "unknown"

        DNS zone validity when last checked
      • txtstring
        TXT entry that needs to be present in your DNS zone to validate domain ownership.
      Optional
      • last_checked_atdatetime
        Date of the last check for zone validity
      • last_checked_atdatetime
        Date of the last check for zone validity
    • statusstring

      One of: "being_created", "running", "being_deleted", "locked", "waiting_ownership", "ownership_validated", "validation_failed"

    Optional
    • applicationobject

      With the following properties:

      • namestring
      • namestring
      • statusstring

        One of: "error", "running", "being_created", "cancelled"

      Optional
      • parametersobject
      • parametersobject
    • certificatesarray

      Of items of type:

      • object

        With the following properties:

        • hrefstring
        • idstring
        • pendingboolean
    • https_strategystring

      One of: "HTTP_only", "allow_HTTP_and_HTTPS", "redirect_HTTP_to_HTTPS"

      Describes the strategy used regarding secure connection to your vhost (HTTP/HTTPS). This field is only present if you have a certificate.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

patch Update a vhost

This route is used to update a vhost

Request

URI Parameters
    • instance_idstring
      UUID of an instance.
    • vhost_fqdnstring
      fqdn of a vhost.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Optional
    • applicationobject

      With the following properties:

      Required
      • namestring
      Optional
      • parametersobject
    • https_strategystring

      One of: "HTTP_only", "allow_HTTP_and_HTTPS", "redirect_HTTP_to_HTTPS"

      Describes the strategy used regarding secure connection to your vhost (HTTP/HTTPS). This field is only present if you have a certificate.
    • linked_dns_zoneobject

      With the following properties:

      Required
      • allow_alterationboolean
        True if you authorized Gandi to modify your DNS zone so that your vhost points to our Simple Hosting public endpoints. If set to True and your DNS zone is managed by our liveDNS platform, you will not have to manually change your DNS configuration to validate your vhost ownership. Check last_checked_status to validate.
      Optional
      • allow_alteration_overrideboolean

        Default: false

        True to override your DNS zone if there already is a record to link your instance to your vhost fqdn.

Responses

200

Body
  • application/json
    object

    With the following properties:

    • fqdnstring
      fqdn of the vhost.
    • https_strategystring

      One of: "HTTP_only", "allow_HTTP_and_HTTPS", "redirect_HTTP_to_HTTPS"

      Describes the strategy used regarding secure connection to your vhost (HTTP/HTTPS). This field is only present if you have a certificate.
    • linked_dns_zoneobject

      With the following properties:

      • allow_alterationboolean
        True if you authorized Gandi to modify your DNS zone so that your vhost points to our Simple Hosting public endpoints. If set to True and your DNS zone is managed by our liveDNS platform, you will not have to manually change your DNS configuration to validate your vhost ownership. Check last_checked_status to validate.
      • last_checked_statusstring

        One of: "altered", "livedns_conflict", "livedns_done", "livedns_error", "unknown"

        DNS zone validity when last checked
    • statusstring

      One of: "being_created", "running", "being_deleted", "locked", "waiting_ownership", "ownership_validated", "validation_failed"

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

delete Delete a vhost

This route is used to delete a vhost of an instance.

Request

URI Parameters
    • instance_idstring
      UUID of an instance.
    • vhost_fqdnstring
      fqdn of a vhost.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

204

Vhost is deleted

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Simple Hosting vhost cache information

https://api.gandi.net/v5/simplehosting/instances/{instance_id}/vhosts/{vhost_fqdn}/cache

delete Purge a vhost's cache

This route is used to purge the cache of a Simplehosting vhost

Request

URI Parameters
    • instance_idstring
      UUID of an instance.
    • vhost_fqdnstring
      fqdn of a vhost.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

204

Vhost's cache is purged

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key