REST API

REST API enables you to access your Upstash database using REST.

Get Started

If you do not have a database already, follow these steps to create one.

In the database details section of the Upstash Console, click the REST API button. Copy the REST URL and the authentication token. Send an HTTP GET request to the provided URL by adding an Authorization: Bearer $TOKEN header.

curl https://us1-merry-cat-32748.upstash.io/set/foo/bar \ -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"

The above script executes a SET foo bar command. It will return a JSON response:

{"result":"OK"}

You can also set the token as _token request parameter as below:

curl https://us1-merry-cat-32748.upstash.io/set/foo/bar?_token=2553feg6a2d9842h2a0gcdb5f8efe9934

Read Only Token

Upstash provides two separate auth tokens: Standard and Read Only. Read only token permits access to the read commands only. Some powerful read commands (e.g. SCAN, KEYS) are also restricted with read only token. It makes sense to use read only token when you access Upstash Redis from web and mobile clients where the token is exposed to public.

You can get the read only token using the REST API button in the console.

API Semantics

Upstash REST API follows the same convention with Redis Protocol. Give the command name and parameters in the same order as Redis protocol by separating them with a /.

curl REST_URL/COMMAND/arg1/arg2/../argN

Here are some examples:

• SET foo bar -> REST_URL/set/foo/bar

• SET foo bar EX 100 -> REST_URL/set/foo/bar/EX/100

• GET foo bar -> REST_URL/get/foo

• MGET foo1 foo2 foo3 -> REST_URL/mget/foo1/foo2/foo3

• HGET employee:23381 salary -> REST_URL/hget/employee:23381/salary

• ZADD teams 100 team-x 90 team-y -> REST_URL/zadd/teams/100/team-x/90/team-y

JSON or Binary Value

To post a JSON or a binary value, you can use an HTTP POST request and set value as the request body:

curl -X POST -d '$VALUE' https://us1-merry-cat-32748.upstash.io/set/foo \ -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"

In the example above, $VALUE sent in request body is appended to the command as REST_URL/set/foo/$VALUE.

Note that POST request body is appended as the last parameter of a Redis command. If there are other parameters in Redis command after the value, you should send them as request query parameters:

curl -X POST -d '$VALUE' https://us1-merry-cat-32748.upstash.io/set/foo?EX=100 \ -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"

Above command is equivalent to REST_URL/set/foo/$VALUE/EX/100.

POST Command in Body

Alternatively, you can send the whole command in the request body as a single JSON array. Array's first element must be the command name and command parameters should be appended next to each other in the same order as Redis protocol.

curl -X POST -d '[COMMAND, ARG1, ARG2,.., ARGN]' REST_URL

For example, Redis command SET foo bar EX 100 can be sent inside the request body as:

curl -X POST -d '["SET", "foo", "bar", "EX", 100]' https://us1-merry-cat-32748.upstash.io \ -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"

HTTP Codes

• 200 OK: When request is accepted and successfully executed.

• 400 Bad Request: When there's a syntax error, an invalid/unsupported command is sent or command execution fails.

• 401 Unauthorized: When authentication fails; auth token is missing or invalid.

• 405 Method Not Allowed: When an unsupported HTTP method is used. Only HEAD, GET, POST and PUT methods are allowed.

Response

REST API returns a JSON response. When command execution is successful, response JSON will have a single result field and its value will contain the Redis response. It can be either;

• a null value

{"result":null}

• an integer

{"result":137}

• a string

{"result":"value"}

• an array value:

{"result":["value1", null, "value2"]}

If command is rejected or fails, response JSON will have a single error field with a string value explaining the failure:

{"error":"WRONGPASS invalid password"}
{"error":"ERR wrong number of arguments for 'get' command"}

Pipelining

Upstash REST API supports command pipelining to send multiple commands in batch, instead of sending each command one by one and waiting for response. When pipeline API is used, several commands are sent using a single HTTP request, and a single JSON array response is returned. Each item in the response array corresponds to the command in the same order within the pipeline.

API endpoint for command pipelining is /pipeline. Pipelined commands should be send as a two dimensional JSON array in the request body, each row containing name of the command and its arguments.

Request syntax:

curl -X POST https://us1-merry-cat-32748.upstash.io/pipeline \ -H "Authorization: Bearer $TOKEN" \ -d '    [      ["CMD_A", "arg0", "arg1", ..., "argN"],      ["CMD_B", "arg0", "arg1", ..., "argM"],      ...    ]    '

Response syntax:

[{"result":"RESPONSE_A"},{"result":"RESPONSE_B"},{"error":"ERR ..."}, ...]

note

Execution of the pipeline is not atomic. Even though each command in the pipeline will be executed in order, commands sent by other clients can interleave with the pipeline.

For example you can write the curl command below to send following Redis commands using pipeline:

SET key1 valuexSETEX key2 13 valuezINCR key1ZADD myset 11 item1 22 item2

curl -X POST https://us1-merry-cat-32748.upstash.io/pipeline \ -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934" \ -d '    [      ["SET", "key1", "valuex"],      ["SETEX", "key2", 13, "valuez"],      ["INCR", "key1"],      ["ZADD", "myset", 11, "item1", 22, "item2"]    ]    '

And pipeline response will be:

[{"result":"OK"},{"result":"OK"},{"error":"ERR value is not an integer or out of range"},{"result":2}]

You can use pipelining when;

• You need more throughput, since pipelining saves from multiple round-trip times. (But beware that latency of each command in the pipeline will be equal to the total latency of the whole pipeline.)
• Your commands are independent of each other, response of a former command is not needed to submit a subsequent command.

Security and Authentication

We provide two seperate access tokens per database: Standard and Read Only

You need to add a header to your API requests as Authorization: Bearer $TOKEN or set the token as a url parameter _token=$TOKEN

warning

Do not expose your standard token publicly. Standard token has full privilege over the database. You can expose the read only token as it has access to read commands only.

note

If your access token is leaked, you can revoke it by resetting password of your database.

Optimizing Performance (for advanced users)

In our internal tests comparing the REST API and native Redis API, we see the latency overhead of REST is less than 1 millisecond. But you can still improve latency connecting to the database port directly. The only disadvantage of this approach is that some environments (e.g. CloudFlare Workers) do not allow clients to access ports other than standard ones (80, 443).

You can use the same url with two changes.

• Append the database port to the url.
• If TLS is disabled, use http instead of https.

Optimized Redis URL (TLS enabled):

curl https://us1-merry-cat-32748.upstash.io:32748/set/foo/bar \ -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"

Optimized Redis URL (TLS disabled):

curl http://us1-merry-cat-32748.upstash.io:32748/set/foo/bar \ -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"

Redis Protocol vs REST API

REST API Pros

• If you want to access to Upstash database from an environment like CloudFlare Workers, WebAssembly, Fastly Compute@Edge then you can not use Redis protocol as it is based on TCP. You can use REST API in those environments.

• REST API is request (HTTP) based where Redis protocol is connection based. If you are running serverless functions (AWS Lambda etc), you may need to manage the Redis client's connections. REST API does not have such an issue.

• Redis protocol requires Redis clients. On the other hand, REST API is accessible with any HTTP client.

Redis Protocol Pros

• If you have a legacy code based on Redis clients, Redis protocol will help you to use Upstash without a code change.

• Using Redis protocol, you can benefit from the rich Redis ecosystem. For example, you can directly use your Upstash database as session cache for your express application.

REST API vs GraphQL API

REST API has lower latency than GraphQL API. With REST API, you directly access to the database. With GraphQL API, there is a proxy layer which accepts the connections and translate GraphQL queries to the Redis protocol.

note

If you do not have a specific GraphQL use case, we recommend REST API instead of GraphQL API. We plan to deprecate the GraphQL API in future releases.

Cost and Pricing

Upstash pricing is based on per command/request. So the same pricing listed in our pricing applies to your REST calls too.

Metrics and Monitoring

In the current version, we do not expose any metrics specific to API calls in the console. But the metrics of the database backing the API should give a good summary about the performance of your APIs.

REST - Redis API Compatibility

Feature	REST Support?	Notes
String	✅
Hash	✅
List	✅	Blocking commands (BLPOP - BRPOP - BRPOPLPUSH) are not supported.
Set	✅
SortedSet	✅	Blocking commands (BZPOPMAX - BZPOPMIN) are not supported.
Transactions	❌
Generic	✅
Connection	❌	Only PING and ECHO are supported.
Server	✅
Scripting	❌
Pub/Sub	❌
Cluster	❌
Geo	❌
HyperLogLog	❌
Streams	❌