Vercel KV Rest API
Learn how to access and use your KV database with the Vercel KV Rest API.Vercel KV is available on Hobby and Pro plans
You can send Redis commands to Vercel KV in the following ways:
- Any Redis client
- Vercel KV SDK
- Vercel KV API
You should only use Vercel KV API if you're using a runtime that does not have a Redis client, or does not support Node.js or Edge.
To get started using Vercel KV API, you need your database's REST API URL and REST API token, which Vercel generates when you connect your project. You'll find your URL and token in your project's dashboard under the following environment variables:
KV_REST_API_URL
KV_REST_API_TOKEN
To access them locally run the following command at the root directory of your project, using Vercel CLI:
vercel env pull .env.development.local
You can then use the environment variables in your code with process.env
:
fetch(`${process.env.KV_REST_API_URL}`, {
headers: {
Authorization: `Bearer ${process.env.KV_REST_API_TOKEN}`,
},
})
.then((response) => response.json())
.then((data) => console.log(data));
Or with the _token
query parameter to authenticate your requests.
const { KV_REST_API_URL, KV_REST_API_TOKEN } = process.env;
fetch(`${KV_REST_API_URL}?_token=${KV_REST_API_TOKEN}`)
.then((response) => response.json())
.then((data) => console.log(data));
Vercel automatically generates an API URL when you connect your KV database to a project, which you can find under Endpoint on your database information page.
To make requests to your API URL, pass the API token in the Authorization
header using the code from the Fetch tab of the dashboard quickstart:
Vercel KV also generates a read-only API token, which grants access only to read commands. It also disables the KEYS
command. You can access your read-only token with the KV_REST_API_READ_ONLY_TOKEN
environment variable.
You can send basic commands in two ways:
- Add commands to the path of your API URL, separating each element of the command into their own paths with a
/
.- If a value contains slashes, such as setting a key named
redirectURL
tohttps://example.com
, you must send commands in thebody
.
- If a value contains slashes, such as setting a key named
- Send Redis commands in the
body
of aPOST
request to your KV API URL. You must break each parameter of the command out into items in an array. Commands can have as many parameters as is allowed by the Redis Protocol.
[path]/set/{key}/{value}/{options}
Example
Define in path:
// SET userId abc EX 100
fetch(`${process.env.KV_REST_API_URL}/set/userId/abc/ex/100`, {
headers: {
Authorization: `Bearer ${process.env.KV_REST_API_TOKEN}`,
},
})
.then((response) => response.json())
.then((data) => console.log(data));
Define in body:
fetch(`${process.env.KV_REST_API_URL}/`, {
headers: {
Authorization: `Bearer ${process.env.KV_REST_API_TOKEN}`,
},
body: '["HSET", "sessionData", "username", "exampleUser123"]',
method: 'POST',
})
.then((response) => response.json())
.then((data) => console.log(data));
Parameters | Required | Type | Description |
---|---|---|---|
key | Yes | string | The name of the key |
value | Yes | string, number or boolean | The value to set |
options | No | object | An object whose keys can be command arguments |
[path]/get/{key}
Example
Define in path:
fetch(`${process.env.KV_REST_API_URL}/get/userId`, {
headers: {
Authorization: `Bearer ${process.env.KV_REST_API_TOKEN}`,
},
})
.then((response) => response.json())
.then((data) => console.log(data));
Define in body:
fetch(`${process.env.KV_REST_API_URL}/`, {
headers: {
Authorization: `Bearer ${process.env.KV_REST_API_TOKEN}`,
},
body: '["GET", "userId"]',
method: 'POST',
})
.then((response) => response.json())
.then((data) => console.log(data));
Parameters | Required | Type | Description |
---|---|---|---|
key | Yes | string | The name of the key |
- url =
${process.env.KV_REST_API_URL}/set/{key}
- method = POST
- Body = JSON object
// SET userSession jsonObject
fetch(`${process.env.KV_REST_API_URL}/set/userSession`, {
headers: {
Authorization: `Bearer ${process.env.KV_REST_API_TOKEN}`,
},
body: JSON.stringify({
sessid: '12345',
session_name: 'abcdef',
user: {
uid: 31,
name: 'test_user',
mail: 'user@example.com',
},
}),
method: 'POST',
})
.then((response) => response.json())
.then((data) => console.log(data));
Path Parameters
Path Parameters | Required | Type | Description |
---|---|---|---|
key | Yes | string | The name of the key |
This allows you to store user file contents in your KV database.
Endpoint:
- url =
${process.env.KV_REST_API_URL}/set/binaryKey
- method = POST
- Body = Binary data, such as files attached through HTML
<input>
elements
Example
export default function FileInput() {
const fileInputRef = useRef<HTMLInputElement | null>(null);
function setFileToKey() {
if (!fileInputRef?.current?.files) {
return console.log('No file found');
}
fetch(`${process.env.KV_REST_API_URL}/set/binaryKey`, {
headers: {
Authorization: `Bearer ${process.env.KV_REST_API_TOKEN}`,
},
body: fileInputRef.current.files[0],
method: 'POST',
})
.then((response) => response.json())
.then((data) => console.log(data));
}
return (
<>
<input ref={fileInputRef} type="file" />
<button onClick={setFileToKey}>Upload file</button>
</>
);
}
There are two ways to send multiple commands to your KV database from the Rest API:
- Pipelining - Pipelining executes multiple commands in one network request. However, pipelining is not atomic, so other client requests can be processed in the between.
- Transactions - Transactions allow you to send multiple commands to your KV database in one network request. However, transactions are executed atomically, which means commands sent from other client instances will not be executed in between a transaction's commands.
Endpoint:
- url=
${process.env.KV_REST_API_URL}/pipeline
- method = POST
- body = Redis commands in a two-dimensional array. Define arguments in the same order that you would with a standard Redis command
Example
fetch(`${process.env.KV_REST_API_URL}/pipeline`, {
headers: {
Authorization: `Bearer ${process.env.KV_REST_API_TOKEN}`,
},
// SET userEmail example@example.com EX 100
// GET userEmail
body: `[
["SET", "userEmail", "example@example.com", "EX", 100],
["GET", "userEmail"]
]`,
method: 'POST',
})
.then((response) => response.json())
.then((data) => console.table(data));
Endpoint:
- url =
${process.env.KV_REST_API_URL}/multi-exec
- method = POST
- body = Redis commands in a two-dimensional array. Define arguments in the same order that you would with a standard Redis command
Example
fetch(`${process.env.KV_REST_API_URL}/multi-exec`, {
headers: {
Authorization: `Bearer ${process.env.KV_REST_API_TOKEN}`,
},
// HSET sessionData userEmail example@example.com
// HGET sessionData userEmail
body: `[
["HSET", "sessionData", "userEmail", "example@example.com"],
["HGET", "sessionData", "userEmail"]
]`,
method: 'POST',
})
.then((response) => response.json())
.then((data) => console.table(data));
Response
If your transaction is successful, the response will be an array of result objects in the same order as the commands. The following is an example response array:
[
{
"result": "OK"
},
{
"result": "example@example.com"
}
]
The following table displays the possible HTTP responses you can receive from API requests, and what they mean.
HTTP Code | HTTP Status | Meaning |
---|---|---|
200 | OK | The command was successfully executed. |
400 | Bad Request | The command was invalid/unsupported, contained a syntax error, or failed to execute. |
401 | Unauthorized | Authentication failed, likely due to an invalid or missing API token. |
405 | Method Not Allowed | An unsupported HTTP method was used. Only HEAD , GET , POST , and PUT methods are allowed when making API requests. |
Was this helpful?