NAV
shell

Introduction🔗

Documentation for ElephantSQL API.

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.

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

Parameter Description
db Name of the database (optional) 
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
-d "db=my-db" \
https://api.elephantsql.com/api/backup

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

Parameter Description
db Name of the database (optional)
callback JSON endpoint to POST to when backup is ready (optional) 
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"
}

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

Parameter Description
backup_id The id of the backup to restore
callback JSON endpoint to POST to when database is restored 
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"
}

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

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

Account🔗

Initiate rotation of the user password on your instance.

curl -XPOST -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx \
  https://api.elephantsql.com/api/account/rotate-password

POST https://api.elephantsql.com/api/account/rotate-password

curl -XPOST -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx \
  https://api.elephantsql.com/api/account/rotate-apikey

POST https://api.elephantsql.com/api/account/rotate-apikey

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.

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

Available recipients types:

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

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

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
  }
]

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

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
}

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

Update a specific recipient with new information

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

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": {},
}
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

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

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

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

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

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

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 
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 
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 (unit is gigabytes if calculation fixed)
value_calculation string How to treat value threshold, possible values: fixed (default), percentage
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 
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 
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

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
    }
]

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

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
}

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

Use the id of a specific alarm to update it

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

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.

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

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

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

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"
  }
]

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

Available log integrations are:

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

Parameter Description
SYSTEM The logs system to integrate to, any of these: azure_monitor, cloudwatchlog, coralogix, datadog, logentries, loggly, papertrail, scalyr or splunk

Use Azure portal to configure external access for Azure monitor. Tutorial to find/create all params below.

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d "tenant_id=CHANGEM&application_id=CHANGEME&application_secret=CHANGEME&dce_uri=CHANGEME&table=CHANGEME&dcr_id=CHANGEME" \
  https://api.elephantsql.com/api/integrations/logs/azure_monitor
Parameter Description
tenant_id Directory (tenant) ID.
application_id Application (client) ID. How to create an application
application_secret Application secret
dce_uri Data Collection Endpoint URI. How to create a DCE
table Table name. Table should have the columns: TimeGenerated, Host, Event, Level and Message. How to create a table
dcr_id ID of Data Collection Rule that your DCE is linked to. Find the DCR ID

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

Create a 'Send-Your-Data' private API key, Coralogix documentation

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d "private_key=CHANGEM&endpoint=CHANGEME&application=CHANGEME&subsystem=CHANGEME" \
  https://api.elephantsql.com/api/integrations/logs/coralogix
Parameter Description
private_key The API key used for authentication
endpoint The syslog destination to send the logs to (e.g. syslog.eu2.coralogix.com:6514)
application The "Application Name", see Coralogix documentation
subsystem The "Subsystem Name", see Coralogix documentation

Create a Datadog API key at app.datadoghq.com

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d "api_key=XXXXXXXXXXXXX&region=us1&tags=env=dev" \
  https://api.elephantsql.com/api/integrations/logs/datadog
Parameter Description
api_key The API key ised for authentication
region The region to send the logs, [us1, us3, us5, eu]
tags (Optional) Enter tags for the integration, like this: env=prod,region=europe

Create a Logentries token at logentries add-log

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

Create a Loggly token at https://{your-company}.loggly.com/tokens

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

Create a Papertrail endpoint at papertrail setup

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

Create a Log write token at Scalyr keys

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d "token=XXXXX&host=app.scalyr.com" \
  https://api.elephantsql.com/api/integrations/logs/scalyr
Parameter Description
token The token used for authentication
host Destination to send the logs [app.scalyr.com, app.eu.scalyr.com]

Create a HTTP Event Collector token at https://<your-splunk>.cloud.splunk.com/en-US/manager/search/http-eventcollector

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

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

Parameter Description
INT_ID The ID of the integration to delete 
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":"XXXXXXXXXXXXX",
      "region": "us1",
      "tags": "env=dev"
    },
    "error": "",
    "account_id": "99ed6d99-fjsd-7d7d-8ujd-2f53asf34weaws"
  }
]

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

Available metrics integrations are:

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

Parameter Description
SYSTEM The logs system to integrate to 
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 
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 
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 
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 
curl -XDELETE -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://api.elephantsql.com/api/integrations/metrics/636

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

Parameter Description
INT_ID The ID of the integration to delete

Maintenance🔗

List, run and reschedule maintenance

curl -XGET -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx https://api.elephantsql.com/api/maintenance

The above command returns JSON structured like this:

[
  {
    "id": 1234,
    "scheduled_by": "2022-02-05 00:36:00 +0000",
    "status": "scheduled",
    "required_by": "2022-03-05 00:00:00 +0000",
    "duration": "1 hour",
    "description": "..."
  }
]

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

curl -XPUT -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d '{"scheduled_by":"2022-02-05 00:36:00 +0000"}' \
  -H "Content-type: application/json" \
  https://api.elephantsql.com/api/maintenance/1234

PUT https://api.elephantsql.com/api/maintenance/<ID>

Parameter Description
scheduled_by Date string
Parameter Description
ID Maintenance id 
curl -XPOST -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx https://api.elephantsql.com/api/maintenance/<ID>
Parameter Description
ID Maintenance id

Authentication🔗

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

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx \
  https://api.elephantsql.com/api/<endpoint>

You can find your API key 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🔗

Status Code Meaning
200 The request completed successfully.
204 The request completed successfully.
400 Bad Request -- Your request might be 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.
shell