NAV Navbar
shell python go

Introduction

Welcome to the Upstash API! You can use the API to create and manage your databases.

We have language bindings in Shell, Python, and Go. You can view code examples in the dark area at the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, use this code:

    client := &http.Client{}
    req, err := http.NewRequest("GET", "https://upstash.com/v1/databases", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.SetBasicAuth("EMAIL", "API_KEY")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    bodyText, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)
import requests

response = requests.get('https://upstash.com/v1/databases', auth=('EMAIL', 'API_KEY'))

# With shell, you can just pass the correct header with each request
curl "https://upstash.com/v1/databases"
  -u EMAIL:API_KEY

Make sure to replace EMAIL and API_KEY with your email and API key.

Upstash API requires API keys to authenticate requests. You can view and manage API keys at the Upstash Console.

Upstash API uses HTTP Basic authentication. You should pass EMAIL and API_KEY as basic authentication username and password respectively.

With a client such as curl, you can pass your credentials with the -u option, as the following example shows:

curl https://api.upstash.com/v1/databases -u EMAIL:API_KEY

Databases

Endpoints to create, manage and monitor databases.

All endpoints return responses encoded as JSON.

Create Database

import requests

data = '{\n"database_name":"myredis",\n"region":"eu-west-1",\n"type":"free"\n}'

response = requests.post('https://api.upstash.com/v1/database', data=data, auth=('EMAIL', 'API_KEY'))

curl -X POST \
  https://api.upstash.com/v1/database \
  -u 'EMAIL:API_KEY' \
  -d '{
"database_name":"myredis",
"region":"eu-west-1",
"type":"free"
}'
client := &http.Client{}
var data = strings.NewReader(`{
    "database_name":"myredis",
    "region":"eu-west-1",
    "type":"free"
}`)
req, err := http.NewRequest("POST", "https://api.upstash.com/v1/database", data)
if err != nil {
    log.Fatal(err)
}
req.SetBasicAuth("username", "password")
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)ttn');

Make sure to replace EMAIL and API_KEY with your email and API key. The above command returns a JSON structured like this:

{
    "database_id": "92130612-329f-45a3-b858-dada583ed06c",
    "database_name": "myredisdb",
    "region": "eu-west-1",
    "type": "free",
    "port": 30140,
    "creation_time": 1612811129,
    "state": "active",
    "password": "e12cf384fdf9419fbae726cc5a2cd3b0",
    "user_email": "example@upstash.com",
    "endpoint": "eu1-selected-goat-30138.upstash.io",
    "tls": false
}

This endpoint creates a new Redis database.

Request parameters should be encoded as JSON.

HTTP Request

POST https://api.upstash.com/v1/database

Request Parameters

Parameter Description
database_name Name of the database
region Region of the database. (eu-west-1 or us-east-1)
type Type of the database. (free or standard)

Response Parameters

Parameter Description
database_id ID of the created database
database_name Name of the database
region The region where database is hosted
port Database port for clients to connect
creation_time Creation time of the database as Unix time
state State of database (active or deleted)
password Password of the database
user_email User email
endpoint Endpoint URL of the database
tls TLS/SSL is enabled or not

Upgrade Database

import requests

data = '{\n"type":"standard"\n}'

response = requests.post('https://api.upstash.com/v1/database/:id/upgrade', data=data, auth=('EMAIL', 'API_KEY'))
curl -X POST \
  https://api.upstash.com/v1/database/:id/upgrade \
  -u 'EMAIL:API_KEY' \
  -d '{
"type":"standard"
}'
client := &http.Client{}
var data = strings.NewReader(`{"type":"standard"}`)
req, err := http.NewRequest("POST", "https://api.upstash.com/v1/database/:id/upgrade", data)
if err != nil {
    log.Fatal(err)
}
req.SetBasicAuth("EMAIL", "API_KEY")
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)

Make sure to replace EMAIL and API_KEY with your email and API key. The above command returns JSON structured like this:

{
    "database_id": "92130636-329f-45e3-b858-dada583ed06c",
    "database_name": "myredisdb",
    "region": "eu-west-1",
    "type": "free",
    "port": 30140,
    "creation_time": 1612811129,
    "state": "active",
    "user_email": "example@upstash.com",
    "endpoint": "eu1-selected-foal-30140.upstash.io",
    "tls": false
}

This endpoint upgrades a free database to a standard database.

HTTP Request

POST https://api.upstash.com/v1/database/:id/upgrade

URL Parameters

Parameter Description
ID The ID of the database to upgrade

Request Parameters

Parameter Description
type New type of the database. (standard)

Response Parameters

Parameter Description
database_id ID of the created new database
database_name Name of the database
region The region where the database is deployed
port Port of the database
creation_time Creation time of the database as Unix time
state State of the database (active or deleted)
user_email User email
endpoint Endpoint URL of the database
tls TLS/SSL is enabled or not

Get Database

import requests

response = requests.get('https://api.upstash.com/v1/database/:id', auth=('EMAIL', 'API_KEY'))

curl -X GET \
  https://api.upstash.com/v1/database/:id \
  -u 'EMAIL:API_KEY'
client := &http.Client{}
req, err := http.NewRequest("GET", "https://api.upstash.com/v1/database/:id", nil)
if err != nil {
    log.Fatal(err)
}
req.SetBasicAuth("EMAIL", "API_KEY")
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)

Make sure to replace EMAIL and API_KEY with your email and API key. The above command returns JSON structured like this:

{
    "database_id": "92130636-329f-45e3-b858-dada583ed06c",
    "database_name": "myredisdb",
    "region": "eu-west-1",
    "type": "free",
    "port": 30140,
    "creation_time": 1612811129,
    "state": "active",
    "user_email": "example@upstash.com",
    "endpoint": "eu1-selected-foal-30140.upstash.io",
    "tls": false
}

This API request gets information about a database.

The password is not included in the response of this API request. If you need it, save the password when you first created the database.

HTTP Request

GET https://api.upstash.com/v1/database/:id

URL Parameters

Parameter Description
ID The ID of the database to retrieve

Response Parameters

Parameter Description
database_id ID of the created new database
database_name Name of the database.
region The region where database is deployed
port Port of the database
creation_time Creation time of the database as Unix time
state State of the database (active or deleted)
user_email User email
endpoint Endpoint URL of the database
tls SSL is enabled or not

Get All Databases

import requests

response = requests.get('https://api.upstash.com/v1/databases', auth=('EMAIL', 'API_KEY'))

curl -X GET \
  https://api.upstash.com/v1/databases \
  -u 'EMAIL:API_KEY'
client := &http.Client{}
req, err := http.NewRequest("GET", "https://api.upstash.com/v1/databases", nil)
if err != nil {
    log.Fatal(err)
}
req.SetBasicAuth("EMAIL", "API_KEY")
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)

Make sure to replace EMAIL and API_KEY with your email and API key. The above command returns JSON structured like this:

[
    {
        "database_id": "10436fd0-4b9a-439e-a638-0781e987627b",
        "database_name": "anotherdb",
        "region": "eu-west-1"
    },
    {
        "database_id": "fdc9c824-cfec-4b5b-9fb7-1e4cd8190675",
        "database_name": "freedb",
        "region": "eu-west-1"
    }
]

This endpoint retrieves all databases.

HTTP Request

GET https://api.upstash.com/v1/databases

Response Parameters

Parameter Description
database_id ID of the created new database
database_name Name of the database.
region The region where the database is deployed

Delete Database

import requests

response = requests.delete('https://api.upstash.com/v1/database/:id', auth=('EMAIL', 'API_KEY'))

curl -X DELETE \
  https://api.upstash.com/v1/database/:id \
  -u 'EMAIL:API_KEY'
    client := &http.Client{}
    req, err := http.NewRequest("DELETE", "https://upstash.com/v1/database/:id", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.SetBasicAuth("EMAIL", "API_KEY")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    bodyText, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)

This endpoint deletes a specific database.

Teams

Endpoints to create, manage Upstash teams.

All endpoints return responses encoded as JSON.

Create Team

import requests

data = '{\n"team_name":"myteam"}'

response = requests.post('https://api.upstash.com/v1/team', data=data, auth=('EMAIL', 'API_KEY'))

curl -X POST \
  https://api.upstash.com/v1/team \
  -u 'EMAIL:API_KEY' \
  -d '{
"team_name":"myteam"
}'
client := &http.Client{}
var data = strings.NewReader(`{
    "team_name":"myteam"
}`)
req, err := http.NewRequest("POST", "https://api.upstash.com/v1/team", data)
if err != nil {
    log.Fatal(err)
}
req.SetBasicAuth("username", "password")
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)ttn');

Make sure to replace EMAIL and API_KEY with your email and API key. The above command returns a JSON structured like this:

{
    "team_id": "e453f34d-4018-45a0-b394-08a146f2a5af",
    "team_name": "myteam"
}

This endpoint creates Upstash Team.

Request parameters should be encoded as JSON.

HTTP Request

POST https://api.upstash.com/v1/team

Request Parameters

Parameter Description
team_name Name of the team

Response Parameters

Parameter Description
team_id ID of the created team
team_name Name of the team

Delete Team

import requests

response = requests.delete('https://api.upstash.com/v1/team/:id', auth=('EMAIL', 'API_KEY'))
curl -X DELETE \
  https://api.upstash.com/v1/team/:id \
  -u 'EMAIL:API_KEY'
client := &http.Client{}
req, err := http.NewRequest("DELETE", "https://api.upstash.com/v1/team/:id",nil)
if err != nil {
    log.Fatal(err)
}
req.SetBasicAuth("EMAIL", "API_KEY")
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)

Make sure to replace EMAIL and API_KEY with your email and API key. The above command returns JSON structured like this:

This endpoint deletes a team.

HTTP Request

DELETE https://api.upstash.com/v1/team/:id

URL Parameters

Parameter Description
ID The ID of the Team to delete

Get Teams

import requests

response = requests.get('https://api.upstash.com/v1/teams', auth=('EMAIL', 'API_KEY'))

curl -X GET \
  https://api.upstash.com/v1/teams \
  -u 'EMAIL:API_KEY'
client := &http.Client{}
req, err := http.NewRequest("GET", "https://api.upstash.com/v1/teams", nil)
if err != nil {
    log.Fatal(err)
}
req.SetBasicAuth("EMAIL", "API_KEY")
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)

Make sure to replace EMAIL and API_KEY with your email and API key. The above command returns JSON structured like this:

{
    "team_id": "e453f34d-4018-45a0-b394-08a146f2a5af",
    "team_name": "newteam",
    "member_role": "owner"
},
{
    "team_id": "45011e59-507a-4faf-98dd-2001eeb3b261",
    "team_name": "secondteam",
    "member_role": "finance"
}

This API request all teams for the user.

HTTP Request

GET https://api.upstash.com/v1/teams

Response Parameters

Parameter Description
team_id ID of the team
team_name Name of the team.
member_role Role of the member in the team

Add Team Member

import requests

data = '{"team_id":"e453f34d-08a146f2a5af","member_email":"user@upstash.com","member_role":"finance"}'
response = requests.post('https://api.upstash.com/v1/member', data=data, auth=('EMAIL', 'API_KEY'))

curl -X POST \
  https://api.upstash.com/v1/member \
  -u 'EMAIL:API_KEY' \
  -d '{
"team_id":"e453f34d-08a146f2a5af",
"member_email":"user@upstash.com",
"member_role":"finance"
}'
client := &http.Client{}
var data = strings.NewReader(`{
    "team_id":"e453f34d-08a146f2a5af",
    "member_email":"user@upstash.com",
    "member_role":"finance"
}`)
req, err := http.NewRequest("POST", "https://api.upstash.com/v1/member", data)
if err != nil {
    log.Fatal(err)
}
req.SetBasicAuth("EMAIL", "API_KEY")
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)

Make sure to replace EMAIL and API_KEY with your email and API key. The above command returns JSON structured like this:

This endpoint adds a member to a team.

HTTP Request

POST https://api.upstash.com/v1/member

Delete Team Member

import requests
data = '{"team_id":"e453f34d-08a146f2a5af","member_email":"user@upstash.com"}'
response = requests.delete('https://api.upstash.com/v1/member', data=data, auth=('EMAIL', 'API_KEY'))

curl -X DELETE \
  https://api.upstash.com/v1/member \
  -u 'EMAIL:API_KEY' \
  -d '{
      "team_id":"e453f34d-08a146f2a5af",
      "member_email":"user@upstash.com"
      }'
    client := &http.Client{}
  var data = strings.NewReader(`{
      "team_id":"e453f34d-08a146f2a5af",
      "member_email":"user@upstash.com"
  }`)
    req, err := http.NewRequest("DELETE", "https://upstash.com/v1/member", data)
    if err != nil {
        log.Fatal(err)
    }
    req.SetBasicAuth("EMAIL", "API_KEY")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    bodyText, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)

This endpoint deletes a team member.

HTTP Request

DELETE https://api.upstash.com/v1/member

Get Team Members

import requests
response = requests.get('https://api.upstash.com/v1/members/:id', auth=('EMAIL', 'API_KEY'))
curl -X GET \
  https://api.upstash.com/v1/members/:id \
  -u 'EMAIL:API_KEY'
client := &http.Client{}
req, err := http.NewRequest("GET", "https://api.upstash.com/v1/members/:id", nil)
if err != nil {
    log.Fatal(err)
}
req.SetBasicAuth("EMAIL", "API_KEY")
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)

The above command returns JSON structured like this:

[
    {
        "team_id": "e453f34d-4018-45a0-b394-08a146f2a5af",
        "team_name": "newteam",
        "member_email": "test@upstash.com",
        "member_role": "owner"
    }
]

HTTP Request

GET https://api.upstash.com/v1/members/:id

URL Parameters

Parameter Description
ID The ID of the team to retrieve all members and roles.

Response Parameters

Parameter Description
team_id ID of the team
team_name Name of the team
member_email Email of the member
member_role Role of the member

HTTP Status Codes

The Upstash API uses the following HTTP Status codes:

Error Code Meaning
200 OK -- Indicates that a request completed successfully and the response contains data.
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.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.