NAV
shell

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.
429 Too Many Requests -- Rate limiting, you have requested too many kittens in a given amount of time.
500 Internal Server Error -- We had a problem with our server. Try again later.