Last updated on June 7, 2023

9 min read

Vercel KV Rest API

Learn how to access and use your KV database with the Vercel KV Rest API.

Vercel KV is available in Beta on Pro and Hobby plans

You can send Redis commands to Vercel KV in the following ways:

Any Redis client
Vercel KV SDK
Vercel KV API

Note: 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.

Getting started

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:

basic-request-example.ts

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.

token-param-example.ts

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));

Making a request without environment variables

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:

Read-only API token

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.

Sending basic commands

You can do 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 to https://example.com, you must send commands in the body.
Send Redis commands in the body of a POST 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.

Set

[path]/set/{key}/{value}/{options}

Example

Define in path:

define-in-path-example.ts

// 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:

request-body-example.ts

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

Get

[path]/get/{key}

Example

Define in path:

define-in-path-example.ts

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:

request-body-example.ts

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

Sending commands with JSON data

url = ${process.env.KV_REST_API_URL}/set/{key}
method = POST
Body = JSON object

example-fetch.ts

// 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

Sending commands with Binary data

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 via HTML <input> elements

Example

file-input.tsx

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>
    </>
  );
}

Sending multiple commands

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.

Using pipelining

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

pipelining-example.ts

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));

Sending Redis transactions

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

transaction-example.ts

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:

Transaction response example

[
  {
    "result": "OK"
  },
  {
    "result": "example@example.com"
  }
]

Errors

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.

Table of Contents

Was this helpful?