Endpoint
or Token / Readonly Token
fields, copy button will appear for each. You can click it to easily copy the values you need for your connection.
Copy the HTTPS
for REST URL and the Token
for authorization. Send an HTTP SET request to the
provided URL by adding an Authorization: Bearer $TOKEN
header like below: (See the sample command with your credentials in the cURL
tab of Connection section)
SET foo bar
command. It will return a JSON
response:
_token
request parameter as below:
/
.
SET foo bar
-> REST_URL/set/foo/bar
SET foo bar EX 100
-> REST_URL/set/foo/bar/EX/100
GET foo
-> 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
$VALUE
sent in request body is appended to the command
as REST_URL/set/foo/$VALUE
.
Please note that when making a POST request to the Upstash REST API, the request
body is appended as the last parameter of the Redis command. If there are
additional parameters in the Redis command after the value, you should include
them as query parameters in the request:
REST_URL/set/foo/$VALUE/EX/100
.
SET foo bar EX 100
can be sent inside the request
body as:
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.
result
field and its value will contain the Redis
response. It can be either;
null
valueerror
field
with a string value explaining the failure:
BITOP NOT
etc.
If you prefer the raw response in base64 format, you can achieve this by setting
the Upstash-Encoding
header to base64
. In this case, all strings in the response
will be base64 encoded, except for the “OK” response.
application/json
.
If you prefer the binary response in RESP2 format, you can achieve this by setting
the Upstash-Response-Format
header to resp2
. In this case, the response content type
is set to application/octet-stream
and the raw response is returned as binary similar to a TCP-based Redis client.
The default value for this option is json
.
Any format other than json
and resp2
is not allowed and will result in a HTTP 400 Bad Request.
This option is not applicable to /multi-exec
transactions endpoint, as it only returns response in JSON format.
Additionally, setting the Upstash-Encoding
header to base64
is not permitted when the Upstash-Response-Format
is set to resp2
and will result in a HTTP 400 Bad Request.
/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
command below to send following Redis
commands using pipeline:
/multi-exec
. Transaction 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
command below to send following Redis commands using
REST transaction API:
MONITOR
command using
Server Send Events mechanism. API endpoint is /monitor
.
MONITOR
command, Upstash REST API provides Redis SUBSCRIBE
and
PUBLISH
commands. The SUBSCRIBE
endpoint works using/subscribe
and /publish
Following request will subscribe to a channel named chat
:
chat
:
Authorization: Bearer $TOKEN
or set the token as a url parameter _token=$TOKEN
.
UPSTASH_REDIS_REST_TOKEN
in REST API section of the console. For the Read
Only token, just enable the “Read-Only Token” switch.
ACL SETUSER
command. Upstash provides a custom ACL
subcommand to generate REST tokens:
ACL RESTTOKEN
. It expects two arguments; username and user’s password. And
returns the REST token for the user as a string response.
ACL RESTTOKEN
command via redis-cli
:
Feature | REST Support? | Notes |
---|---|---|
String | ✅ | |
Bitmap | ✅ | |
Hash | ✅ | |
List | ✅ | Blocking commands (BLPOP - BRPOP - BRPOPLPUSH) are not supported. |
Set | ✅ | |
SortedSet | ✅ | Blocking commands (BZPOPMAX - BZPOPMIN) are not supported. |
Geo | ✅ | |
HyperLogLog | ✅ | |
Transactions | ✅ | WATCH/UNWATCH/DISCARD are not supported |
Generic | ✅ | |
Server | ✅ | |
Scripting | ✅ | |
Pub/Sub | ⚠️ | Only PUBLISH and PUBSUB are supported. |
Connection | ⚠️ | Only PING and ECHO are supported. |
JSON | ✅ | |
Streams | ✅ | Supported, except blocking versions of XREAD and XREADGROUP. |
Cluster | ❌ |