NAV Navbar
shell
  • Introduction
  • Backups
  • Alarms
  • Integrations
  • Authentication
  • Formats
  • Status Codes
  • Introduction

    Documentation for ElephantSQL API.

    Backups

    List backups

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/backup?db=my-db
    

    The above command returns JSON structured like this:

    [
      {
        "id":7,
        "database_id":"5abb0624-909b-4e79-aa7a-f488dcae752b",
        "backup_date":"2017-05-15 15:03:14+0200",
        "size":2221,
        "bucket":null,
        "file_name":"nutty-jackfruit/tyicyjck.2017-05-15.sql.lzo",
        "region":"amazon-web-services::us-east-1",
        "database_name":"tyicyjck",
        "url":"https://elephantsql-backups-us-east-1.s3.amazonaws.com/nutty-jackfruit/tyicyjck.2017-05-15.sql.lzo?AWSAccessKeyId=AKIAIDFGDFGEDIGRVQ&Expires=1494865612&Signature=t3Hi7iKASDB%vfBlAjPLgTYsaQ%3D"
      }
    ]
    

    List backups for last 30 days, ordered with the most recent first.

    HTTP Request

    GET https://api.elephantsql.com/api/backup

    Request Parameters

    Parameter Description
    db Name of the database (optional)

    Create backup

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
    -d "db=my-db" \
    https://api.elephantsql.com/api/backup
    

    HTTP Request

    POST https://api.elephantsql.com/api/backup

    Request Parameters

    Parameter Description
    db Name of the database (optional)
    callback JSON endpoint to POST to when backup is ready (optional)

    Restore backup

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
    -d "backup_id=1234" \
    https://api.elephantsql.com/api/backup/restore
    

    The optional callback gets a request with this body

    {
      "action": "restore",
      "backup_id": 4,
      "account_id": "5abb0624-909b-4e79-aa7a-f488dcae752b"
    }
    

    HTTP Request

    POST https://api.elephantsql.com/api/backup/restore

    Request Parameters

    Parameter Description
    backup_id The id of the backup to restore
    callback JSON endpoint to POST to when database is restored

    Point in time recovery

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
    -d "pit=2018-01-01%2000%3A00" \
    https://api.elephantsql.com/api/backup/pitr
    

    The optional callback gets a request with this body

    {
      "action": "pitr",
      "account_id": "5abb0624-909b-4e79-aa7a-f488dcae752b"
    }
    

    HTTP Request

    POST https://api.elephantsql.com/api/backup/pitr

    Request Parameters

    Parameter Description
    pit Time to recover to (yyyy-mm-dd hh:mm)
    callback JSON endpoint to POST to when database is restored

    Alarms

    Information about both alarms, notifications and recipient. When creating a new instace, a set of default alarms and recipient will be created.

    Recipient: There will always be a default recipient created, using the team email set during sign up. This recipient is used to receive notifications from the default alarms.

    Alarm: There will always be four default alarms created, cpu, memory, disk and notice alarms.

    Create recipient

    To use another recipient than default recipient, a new one needs to be created.

    Available recipients types:

    HTTP Request

    POST https://api.elephantsql.com/api/alarms/recipients

    Example of email recipient

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "type=email&value=notification@example.com&name=low"
      https://api.elephantsql.com/api/alarms/recipients
    

    This creates an email recipient for notification@example.com that can be used to receive alarm notifications. The returned JSON structured look like this:

    {
      "id": 2,
      "type": "email",
      "value": "notification@example.com",
      "name": "Low",
      "options": {},
    }
    

    Request body parameters

    Parameter Required Type  Description
    type true string The type of notification to be sent
     value true string Endpoint to where the notification will be sent
    name false string Optional, name for the recipient

    List recipients

    Retrieve all recipients for an instance that can receive notifications

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/alarms/recipients
    

    The above command returns JSON structured like this:

    [
      {
        "id": 1,
        "type": "email",
        "value": "team@84codes.com",
        "name": "Default",
        "options": null
      },
      {
        "id": 2,
        "type": "email",
        "value": "notification@example.com",
        "name": "Low",
        "options": null
      }
    ]
    

    HTTP Request

    GET https://api.elephantsql.com/api/alarms/recipients

    Retrieve specific recipient

    Use the id of a recipient to retrieve it

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/alarms/recipients/1
    

    The above command returns JSON structured like this:

    {
      "id": 1,
      "type": "email",
      "value": "team@example.com",
      "name": "Default",
      "options": null
    }
    

    HTTP Request

    GET https://api.elephantsql.com/api/alarms/recipients/<id>

    Update recipient

    Update a specific recipient with new information

    HTTP Request

    PUT https://api.elephantsql.com/api/alarms/recipients/<id>

    Example of email recipient

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "type=email&value=alarms@example.com&name=High"
      https://api.elephantsql.com/api/alarms/recipients/2
    

    This updates an email recipient for notification@example.com that can be used to receive alarm notifications. The returned JSON structured look like this:

    {
      "id": 2,
      "type": "email",
      "value": "alarm@example.com",
      "name": "High",
      "options": {},
    }
    

    URL Parameters

    Parameter  Description
    id  The recipient identifier

    Request body parameters

    Parameter Required Type  Description
    type true string The type of notification to be sent
     value true string Endpoint to where the notification will be sent
    name false string Optional, name for the recipient

    Delete recipient

    Use the id of a specific recipient to remove it

    curl -XDELETE -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/alarms/recipients/2
    

    HTTP Request

    DELETE https://api.elephantsql.com/api/alarms/recipients/<id>

    URL Parameters

    Parameter Description
     id Use the id of the recipient that you want to delete

    Create alarm

    Available alarms types: | Name | Type | Dedicated | Shared | Description | |------|------|------|------|------| | CPU | cpu | yes | - | Alarm if CPU usage is above a certain level for a period of time | | Memory | memory | yes | - | Alarm if memory usage is above a certain level for a period of time | | Disk space | disk | yes | - | Alarm id disk usage is above a certain level for a period of time | | Net split | netsplit | yes | - | Alarm if net split occurs | | Server unreachable | server_unreachable | yes | - | Alarm if server is unreachable | | Notice | notice | yes | yes | Notifications on events such as planned or emergency maintenance |

    HTTP Request

    POST https://api.elephantsql.com/api/alarms

    Request (CPU alarm)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "type=cpu&enabled=true&value_threshold=90&time_threshold=600&recipients=[1]"
      https://api.elephantsql.com/api/alarms
    

    This sets the alarm to trigger if the CPU usage is above 90% for 10 minutes or more.

    {
      "type": "cpu",
      "enabled": true,
      "value_threshold": 90,
      "time_threshold": 600,
      "recipients": [1]
    }
    
    Parameter Type Description
    type string The alarm type, valid types see table Available alarms types above
    enabled bool Enable or disable the alarm
    value_threshold int The value threshold to trigger the alarm
    time_threshold int For how long (in seconds) the value_threshold should be active before trigger alarm
    recipients []int Recipients identifiers for which should receive notifications when the alarm trigger

    Request (Memory alarm)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "type=memory&enabled=true&value_threshold=90&time_threshold=600&recipients=[1]"
      https://api.elephantsql.com/api/alarms
    

    This sets the alarm to trigger if the memory usage is above 90% for 10 minutes or more.

    {
      "type": "memory",
      "enabled": true,
      "value_threshold": 90,
      "time_threshold": 600,
      "recipients": [1]
    }
    
    Parameter Type Description
    type string The alarm type, valid types see table Available alarms types above
    enabled bool Enable or disable the alarm
    value_threshold int The value threshold to trigger the alarm
    time_threshold int For how long (in seconds) the value_threshold should be active before trigger alarm
    recipients []int Recipients identifiers for which should receive notifications when the alarm trigger

    Request (Disk space alarm)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "type=disk&enabled=true&value_threshold=5&time_threshold=600&recipients=[1]"
      https://api.elephantsql.com/api/alarms
    

    This sets the alarm to trigger if available disk space is above 5Gb for 10 minutes or more.

    {
      "type": "cpu",
      "enabled": true,
      "value_threshold": 5,
      "time_threshold": 600,
      "recipients": [1]
    }
    
    Parameter Type Description
    type string The alarm type, valid types see table Available alarms types above
    enabled bool Enable or disable the alarm
    value_threshold int The value threshold to trigger the alarm
    time_threshold int For how long (in seconds) the value_threshold should be active before trigger alarm
    recipients []int Recipients identifiers for which should receive notifications when the alarm trigger

    Request (Notice)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "type=notice&enabled=true&recipients=[1]"
      https://api.elephantsql.com/api/alarms
    

    Notifies recipients on events such as planned or emergency maintenance

    {
      "type": "notice",
      "enabled": true,
      "recipients": [1]
    }
    
    Parameter Type Description
    type string The alarm type, valid types see table Available alarms types above
    enabled bool Enable or disable the alarm
    recipients []int Recipients identifiers for which should receive notifications when the alarm trigger

    Request (Server unreachable)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "type=server_unreachable&enabled=true&recipients=[1]"
      https://api.elephantsql.com/api/alarms
    

    Notifies recipients if the server is unreachable

    {
      "type": "server_unreachable",
      "enabled": true,
      "recipients": [1]
    }
    
    Parameter Type Description
    type string The alarm type, valid types see table Available alarms types above
    enabled bool Enable or disable the alarm
    recipients []int Recipients identifiers for which should receive notifications when the alarm trigger

    List alarms

    Retrive all alarms used for the instance.

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/alarms
    

    Example of the default created alarms:

    [
        {
            "time_threshold": 600,
            "value_threshold": 90,
            "id": 7395,
            "type": "cpu",
            "recipients": [],
            "enabled": true
        },
        {
            "time_threshold": 600,
            "value_threshold": 90,
            "id": 7396,
            "type": "memory",
            "recipients": [],
            "enabled": true
        },
        {
            "time_threshold": 600,
            "value_threshold": 5,
            "id": 7397,
            "type": "disk",
            "recipients": [],
            "enabled": true
        },
        {
            "id": 7398,
            "type": "notice",
            "recipients": [],
            "enabled": true
        }
    ]
    

    HTTP Request

    GET https://api.elephantsql.com/api/alarms

    Retrieve specific alarm

    Use the id of a specific alarm to retrieve it.

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/alarms/7395
    

    The above command returns JSON structured like this:

    {
      "time_threshold": 600,
      "value_threshold": 90,
      "id": 7395,
      "type": "cpu",
      "recipients": [1],
      "enabled": true
    }
    

    HTTP Request

    GET https://api.elephantsql.com/api/alarms/<id>

    Update alarm

    Use the id of a specific alarm to update it

    HTTP Request

    PUT https://api.elephantsql.com/api/alarms/<id>

    Request Parameters (CPU alarm)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "type=cpu&enabled=true&value_threshold=90&time_threshold=600&recipients=[1]"
      https://api.elephantsql.com/api/alarms
    

    This sets the alarm to trigger if the CPU usage is above 90% for 10 minutes or more.

    Parameter Type Description
    type string The alarm type, valid types see table Available alarms types above
    enabled bool Enable or disable the alarm
    value_threshold int The value threshold to trigger the alarm
    time_threshold int For how long (in seconds) the value_threshold should be active before trigger alarm
    recipients []int Recipients identifiers for which should receive notifications when the alarm trigger

    For more examples, see under the section about creating alarm.

    Delete alarm

    Use the id for a specific alarm to remove it.

    curl -XDELETE -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/alarms/7395
    

    HTTP Request

    DELETE https://api.elephantsql.com/api/alarms/<id>

    URL Parameters

    Parameter Description
    id Use the id of the alarm that you want to delete

    Integrations

    List log integrations

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/integrations/logs
    

    The above command returns JSON structured like this:

    [
      {
        "id":10,
        "type":"papertrail",
        "config": {
          "url":"logs.papertrail.com:2123"
        },
        "error": "",
        "account_id": "99ed6d99-fjsd-7d7d-8ujd-2f53asf34weaws"
      }
    ]
    

    HTTP Request

    GET https://api.elephantsql.com/api/integrations/logs

    Add log integration

    Available log integrations are:

    HTTP Request

    POST https://api.elephantsql.com/api/integrations/logs/<SYSTEM>

    URL Parameters

    Parameter Description
    SYSTEM The logs system to integrate to, any of these: papertrail, loggly, logentries or splunk

    Request Parameters (cloudwatchlog)

    Need to create an IAM user with programmatic permissions:

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "region=us-west-1&access_key_id=87656789&secret_access_key=09876tyui9876yui98" \
      https://api.elephantsql.com/api/integrations/logs/cloudwatchlog
    
    Parameter Description
    region The AWS region to use
    access_key_id The access key id to use
    secret_access_key The secret that goes with the key id

    Request Parameters (papertrail)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "url=logs.papertrail.com:2123" \
      https://api.elephantsql.com/api/integrations/logs/papertrail
    
    Parameter Description
    url The URL to push the logs to

    Request Parameters (loggly)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "token=XXXXXXXXX" \
      https://api.elephantsql.com/api/integrations/logs/loggly
    
    Parameter Description
    token The token used for authentication

    Request Parameters (logentries)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "token=XXXXXXXXXXXXX" \
      https://api.elephantsql.com/api/integrations/logs/logentries
    
    Parameter Description
    token A TCP token for authentication

    Request Parameters (splunk)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "token=XXXXX&host_port=innput-prd-p-rdq96mdbptj4.cloud.splunk.com:8080" \
      https://api.elephantsql.com/api/integrations/logs/splunk
    
    Parameter Description
    token The token used for authentication
    host_port Destination to send the logs

    Delete log integration

    curl -XDELETE -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/integrations/logs/636
    

    HTTP Request

    DELETE https://api.elephantsql.com/api/integrations/logs/<INT_ID>

    URL Parameters

    Parameter Description
    INT_ID The ID of the integration to delete

    List metrics integrations

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/integrations/metrics
    

    The above command returns JSON structured like this:

    [
      {
        "id":10,
        "type":"datadog",
        "config": {
          "api_key":"THE_API_KEY"
        },
        "error": "",
        "account_id": "99ed6d99-fjsd-7d7d-8ujd-2f53asf34weaws"
      }
    ]
    

    HTTP Request

    GET https://api.elephantsql.com/api/integrations/metrics

    Add metrics integration

    Available metrics integrations are:

    HTTP Request

    POST https://api.elephantsql.com/api/integrations/metrics/<SYSTEM>

    URL Parameters

    Parameter Description
    SYSTEM The logs system to integrate to

    Request Parameters (CloudWatch)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "region=us-west-1&access_key_id=87656789&secret_access_key=09876tyui9876yui98" \
      https://api.elephantsql.com/api/integrations/metrics/cloudwatch
    
    Parameter Description
    region The AWS region to use
    access_key_id The access key id to use (Needs to have the PutMetricData permission)
    secret_access_key The secret that goes with the key id

    Request Parameters (Librato)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "email=my@email.com&api_key=9876thjio90876tyu" \
      https://api.elephantsql.com/api/integrations/metrics/librato
    
    Parameter Description
    email The email registered at librato
    api_key The API key

    Request Parameters (DataDog)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "api_key=XXXXXXXXXXXXX" \
      https://api.elephantsql.com/api/integrations/metrics/datadog
    
    Parameter Description
    api_key The API key

    Request Parameters (NewRelic)

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      -d "license_key=XXXXXXXXXXXXXXXXX" \
      https://api.elephantsql.com/api/integrations/metrics/newrelic
    
    Parameter Description
    license_key The license key for NewRelic

    Delete metric integration

    curl -XDELETE -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
      https://api.elephantsql.com/api/integrations/metrics/636
    

    HTTP Request

    DELETE https://api.elephantsql.com/api/integrations/metrics/<INT_ID>

    URL Parameters

    Parameter Description
    INT_ID The ID of the integration to delete

    Authentication

    Authentication is done by sending your API key in the user field for Basic Auth

    curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx \
      https://api.elephantsql.com/api/api/details
    

    You can find your API here on the details page for your instance.

    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.