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 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
        • 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

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
      • 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

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