NAV
shell

Introduction

Documentation for ElephantSQL 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.elephantsql.com/api/instances

You can find, or create, your API keys at https://customer.elephantsql.com/apikeys

Instances

List instances

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

The above command returns JSON structured like this:

[
  {
    "id": 1234,
    "name": "My test",
    "plan": "turle",
    "region": "amazon-web-services::eu-west-1",
    "url": "postgres://iuyhjiu:iyhjiuyhjmhuhjk@test-speedcar-01.db.elephantsql.com:5432/iuyhjiu",
    "providerid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
]

This endpoint retrieves all instances.

HTTP Request

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

Get instance info

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

The above command returns JSON structured like this:

{
  "id": 1234,
  "plan": "turtle",
  "region": "amazon-web-services::eu-west-1",
  "name": "My test",
  "url": "postgres://iuyhjiu:iyhjiuyhjmhuhjk@test-speedcar-01.db.elephantsql.com:5432/iuyhjiu",
  "providerid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "apikey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
  "ready": true
}

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.elephantsql.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=turtle&region=amazon-web-services::us-east-1" \
https://customer.elephantsql.com/api/instances

The above command returns JSON structured like this:

{
  "id": 2234,
  "url": "postgres://iuyhjiu:iyhjiuyhjmhuhjk@test-speedcar-01.db.elephantsql.com:5432/iuyhjiu",
  "apikey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx"
}

HTTP Request

POST https://customer.elephantsql.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
action standalone (default), fork or pit(point-in-time)
pit Timestamp for pit action, e.g. "2018-10-15 11:40:00 UTC"
pg_version Postgres version, default latest
instance_id Instance id for fork and pit actions

Change an Instance

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

Change the name of the instance or update to a new plan

HTTP Request

PUT https://customer.elephantsql.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.elephantsql.com/api/instances/1234

This endpoint deletes an instance

HTTP Request

DELETE https://customer.elephantsql.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.elephantsql.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.elephantsql.com/api/regions

Team

List team members

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.elephantsql.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.elephantsql.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.
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.