NAV Navbar
shell
  • Introduction
  • Authentication
  • Instances
  • Regions
  • Team
  • Formats
  • Status Codes
  • Introduction

    Documentation for CloudMQTT API.

    This API is used for creating instances and are available to the customer that have signed up via https://www.elephantsql.com.

    We have another API, which is per instance, to manage alarms, integrations and more, which all customers have access to.

    That documentation for the Instance API can be found here: Instance API Documentation

    You can get the API key for the other API from Get instance endpoint.

    Authentication

    Authentication is done by sending your API key in the password field in Basic Auth, the username should be kept empty.

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx \
    https://customer.cloudmqtt.com/api/instances
    

    You can find, or create, your API here: https://customer.cloudmqtt.com/team/api

    Instances

    List instances

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
    https://customer.cloudmqtt.com/api/instances
    

    The above command returns JSON structured like this:

    [
      {
        "id": 1234,
        "name": "My test",
        "plan": "cat",
        "region": "amazon-web-services::eu-west-1"
      }
    ]
    

    This endpoint retrieves all instances.

    HTTP Request

    GET https://customer.cloudmqtt.com/api/instances

    Get instance info

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
    https://customer.cloudmqtt.com/api/instances/1234
    

    The above command returns JSON structured like this:

    {
      "id": 1234,
      "plan": "cat",
      "region": "amazon-web-services::eu-west-1",
      "name": "My test",
      "url": "mqtt://uknsvenh:mzthdsFDUDY4@test-speedcar-01.cloudmqtt.com:1883",
      "apikey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx"
    }
    

    This endpoint retrieves a specific instance.

    The API key returned in this response is the key that you will use for the Instance API that we have. That API is per instance and there you can configure alarms, log and metric integrations and more.

    That documentation for the Instance API can be found here: Instance API Documentation

    HTTP Request

    GET https://customer.cloudmqtt.com/api/instances/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the instance to retrieve

    Create an Instance

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
    -d "name=test&plan=cat&region=amazon-web-services::us-east-1" \
    https://customer.cloudmqtt.com/api/instances
    

    The above command returns JSON structured like this:

    { 
      "id": 2234, 
      "url": "mqtt://uknsvenh:mzthdsFDUDY4@m10.cloudmqtt.com:10001",
      "apikey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx" 
    }
    

    HTTP Request

    POST https://customer.cloudmqtt.com/api/instances

    Request Parameters

    Parameter Description
    name The name of the instance
    plan Which subscription plan to use
    region Name of the region you want to create your instance in

    Change an Instance

    curl -XPUT -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
    -d"name=test2&plan=hedgehog" \
    https://customer.cloudmqtt.com/api/instances/1234
    

    This endpoint changes a instance

    HTTP Request

    PUT https://customer.cloudmqtt.com/api/instances/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the instance to delete

    Request Parameters

    Parameter Description
    name The name of the instance
    plan Which subscription plan to use

    Delete an Instance

    curl -XDELETE -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
    https://customer.cloudmqtt.com/api/instances/1234
    

    This endpoint deletes a instance

    HTTP Request

    DELETE https://customer.cloudmqtt.com/api/instances/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the instance to delete

    Regions

    List available regions

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://customer.cloudmqtt.com/api/regions
    

    The above command returns JSON structured like this:

    [
      {
        "provider": "amazon-web-services",
        "region": "us-east-1",
        "name": "Amazon Web Services - US-East-1 (Northern Virginia)",
        "has_shared_plans": true
      },
      {
        "provider": "google-compute-engine",
        "region": "us-central1",
        "name": "Google Compute Engine - us-central1 (Iowa)",
        "has_shared_plans": true
      }
    ]
    

    HTTP Request

    GET https://customer.cloudmqtt.com/api/regions

    Team

    List team members

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://customer.cloudmqtt.com/api/team
    

    The above command returns JSON structured like this:

    [
      {"id": 14, "email": "john@company.com", "tfa_auth_enabled": false},
      {"id": 1343, "email": "jane@company.com", "tfa_auth_enabled": false}
    ]
    

    HTTP Request

    GET https://customer.cloudmqtt.com/api/team

    Formats

    All API end points support form FormData and JSON in the request. You need to format the request accordingly and if you send the request as JSON be sure to add the content type header Content-type: application/json otherwise the server won't be able to parse your request.

    Status Codes

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The kitten requested is hidden for administrators only.
    404 Not Found -- The specified kitten could not be found.
    405 Method Not Allowed -- You tried to access a kitten with an invalid method.
    500 Internal Server Error -- We had a problem with our server. Try again later.