Data

Provision and use Redis, vector, and full-text search databases instantly — all accessible over REST, no Upstash account, no infrastructure setup, just API calls.

Quick Example

Axios

import { withSapiom } from "@sapiom/axios";
import axios from "axios";

const client = withSapiom(axios.create(), {
  apiKey: process.env.SAPIOM_API_KEY,
  serviceName: "Data Redis",
  agentName: "my-agent",
});

const mgmt = "https://upstash.services.sapiom.ai";

// Step 1: Create a Redis database
const { data: db } = await client.post(`${mgmt}/v1/redis/databases`, {
  name: "my-cache",
  region: "us-east-1",
  ttl: "1d",
});

console.log("Created:", db.id, db.url);

// Step 2: Use it via the resource URL
const { data: result } = await client.post(`${db.url}/set/my-key/my-value`);
console.log(result); // "OK"

Fetch

import { createFetch } from "@sapiom/fetch";

const sapiomFetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
  serviceName: "Data Redis",
  agentName: "my-agent",
});

const mgmt = "https://upstash.services.sapiom.ai";

// Step 1: Create a Redis database
const createRes = await sapiomFetch(`${mgmt}/v1/redis/databases`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "my-cache",
    region: "us-east-1",
    ttl: "1d",
  }),
});

const db = await createRes.json();
console.log("Created:", db.id, db.url);

// Step 2: Use it via the resource URL
await sapiomFetch(`${db.url}/set/my-key/my-value`, { method: "POST" });

How It Works

Sapiom provides a two-plane architecture for data services:

1. Provision a resource — Call the management API at upstash.services.sapiom.ai to create a Redis database, vector index, or search database. You get back a resource URL.
2. Use the resource — Send commands to the resource URL (e.g., https://{id}.redis.data.sapiom.ai). Sapiom proxies requests to the underlying Upstash instance with automatic authentication.

Resources have optional TTLs (time-to-live). When a TTL expires, the resource transitions to expired status and is eventually cleaned up. You can extend a resource’s lifetime by updating its expiresAt field.

Each account can provision up to 50 resources per service (50 Redis databases, 50 vector indexes, 50 search indexes).

Provider

Powered by Upstash. Upstash provides serverless Redis, vector, and full-text search databases with per-request pricing and global replication.

API Reference

Endpoints

Management plane (https://upstash.services.sapiom.ai):

Method	Path	Description
POST	/v1/redis/databases	Create a Redis database
GET	/v1/redis/databases	List all Redis databases
GET	/v1/redis/databases/:id	Get a Redis database
PATCH	/v1/redis/databases/:id	Update a Redis database
DELETE	/v1/redis/databases/:id	Delete a Redis database
POST	/v1/vector/indexes	Create a vector index
GET	/v1/vector/indexes	List all vector indexes
GET	/v1/vector/indexes/:id	Get a vector index
PATCH	/v1/vector/indexes/:id	Update a vector index
DELETE	/v1/vector/indexes/:id	Delete a vector index
POST	/v1/search/indexes	Create a search index
GET	/v1/search/indexes	List all search indexes
GET	/v1/search/indexes/:id	Get a search index
PATCH	/v1/search/indexes/:id	Update a search index
DELETE	/v1/search/indexes/:id	Delete a search index

Data plane (per-resource URLs):

Host Pattern	Description
{id}.redis.data.sapiom.ai	Redis commands (all paths proxied)
{id}.vector.data.sapiom.ai	Vector operations (upsert, query, fetch, etc.)
{id}.search.data.sapiom.ai	Search operations (upsert, search, etc.)

---

Redis

Create Redis Database

Endpoint: POST https://upstash.services.sapiom.ai/v1/redis/databases

Parameter	Type	Required	Description
name	string	Yes	Database name (1-128 characters)
region	string	No	AWS region (default: us-east-1)
ttl	string	No	Time-to-live: 30m, 1h, 1d, etc. Max 30 days

{
  "name": "my-cache",
  "region": "us-east-1",
  "ttl": "1d"
}

Response

{
  "id": "res_ab3k9mzxq1wp7rvnlt82",
  "type": "redis",
  "name": "my-cache",
  "status": "provisioning",
  "url": "https://res_ab3k9mzxq1wp7rvnlt82.redis.data.sapiom.ai",
  "region": "us-east-1",
  "expiresAt": "2026-02-26T13:45:00.000Z",
  "createdAt": "2026-02-25T13:45:00.000Z"
}

Note

Resources start in provisioning status. They transition to active within seconds. Use the resource URL from the response for all subsequent data operations.

Update Redis Database

Endpoint: PATCH https://upstash.services.sapiom.ai/v1/redis/databases/:id

Parameter	Type	Required	Description
name	string	No	New name (1-128 characters)
expiresAt	string	No	New expiry (ISO 8601, must be in the future)

Delete Redis Database

Endpoint: DELETE https://upstash.services.sapiom.ai/v1/redis/databases/:id

Returns 204 No Content on success.

Redis Data Plane

Once provisioned, interact with Redis entirely over REST — no TCP connections or Redis client libraries needed. Send any Upstash Redis REST API command to the resource URL:

// SET a key
await client.post(`${db.url}/set/my-key/my-value`);

// GET a key
const { data } = await client.get(`${db.url}/get/my-key`);

// Pipeline multiple commands
const { data: results } = await client.post(`${db.url}/pipeline`, [
  ["set", "key1", "value1"],
  ["set", "key2", "value2"],
  ["get", "key1"],
]);

---

Vector

Create Vector Index

Endpoint: POST https://upstash.services.sapiom.ai/v1/vector/indexes

Parameter	Type	Required	Description
name	string	Yes	Index name (1-128 characters)
region	string	No	AWS region (default: us-east-1)
dimensions	number	No	Vector dimensions, 1-10000 (default: 1536)
similarityFunction	string	No	cosine, euclidean, or dotProduct (default: cosine)
ttl	string	No	Time-to-live: 30m, 1h, 1d, etc. Max 30 days

{
  "name": "my-embeddings",
  "dimensions": 1536,
  "similarityFunction": "cosine",
  "ttl": "7d"
}

Response

{
  "id": "res_xk7p2mwn9qr4jtbv5s01",
  "type": "vector",
  "name": "my-embeddings",
  "status": "provisioning",
  "url": "https://res_xk7p2mwn9qr4jtbv5s01.vector.data.sapiom.ai",
  "region": "us-east-1",
  "dimensions": 1536,
  "similarityFunction": "cosine",
  "expiresAt": "2026-03-04T13:45:00.000Z",
  "createdAt": "2026-02-25T13:45:00.000Z"
}

Vector Data Plane

Use the Upstash Vector REST API through the resource URL:

// Upsert vectors
await client.post(`${index.url}/upsert`, [
  { id: "doc-1", vector: [0.1, 0.2, ...], metadata: { title: "Hello" } },
  { id: "doc-2", vector: [0.3, 0.4, ...], metadata: { title: "World" } },
]);

// Query similar vectors
const { data } = await client.post(`${index.url}/query`, {
  vector: [0.1, 0.2, ...],
  topK: 5,
  includeMetadata: true,
});

---

Search

Create Search Index

Endpoint: POST https://upstash.services.sapiom.ai/v1/search/indexes

Parameter	Type	Required	Description
name	string	Yes	Index name (1-128 characters)
region	string	No	us-central1 or eu-west-1 (default: us-central1)
ttl	string	No	Time-to-live: 30m, 1h, 1d, etc. Max 30 days

{
  "name": "my-search-index",
  "region": "us-central1",
  "ttl": "7d"
}

Response

{
  "id": "res_mn4q8rvw2xp5kjtb6h93",
  "type": "search",
  "name": "my-search-index",
  "status": "provisioning",
  "url": "https://res_mn4q8rvw2xp5kjtb6h93.search.data.sapiom.ai",
  "region": "us-central1",
  "expiresAt": "2026-03-04T13:45:00.000Z",
  "createdAt": "2026-02-25T13:45:00.000Z"
}

Search Data Plane

Use the Upstash Search REST API through the resource URL.

Caution

All search data plane paths require the index name as a path segment. Using an empty index name returns an error.

// Upsert documents — content is a key-value object matching the index schema
await client.post(`${searchDb.url}/upsert/${indexName}`, [
  { id: "doc-1", content: { title: "TypeScript", text: "TypeScript is a typed superset of JavaScript" } },
  { id: "doc-2", content: { title: "Rust", text: "Rust is a systems programming language" } },
]);

// Search
const { data } = await client.post(`${searchDb.url}/search/${indexName}`, {
  query: "typed programming language",
  topK: 5,
});

---

Resource Status Lifecycle

All resources follow this lifecycle:

Status	Description
provisioning	Resource is being created (transitions to active within seconds)
active	Ready for use
expired	TTL has passed, pending cleanup
deleting	Deletion in progress
deleted	Fully removed

Error Codes

Code	Description
400	Invalid request — check parameter formats (name length, TTL format, dimensions range)
402	Payment required — ensure you’re using the Sapiom SDK
404	Resource not found or not owned by your account
409	Resource is not in a valid state for the operation (e.g., deleting a non-active resource)
410	Resource has expired (data plane only)
422	Resource limit exceeded — maximum 50 per service per account
429	Rate limit exceeded
502	Upstream provisioning error from Upstash

Complete Example

Axios

import { withSapiom } from "@sapiom/axios";
import axios from "axios";

const client = withSapiom(axios.create(), {
  apiKey: process.env.SAPIOM_API_KEY,
  serviceName: "Data Redis",
  agentName: "my-agent",
});

const mgmt = "https://upstash.services.sapiom.ai";

async function cacheWorkflow() {
  // Create a Redis database with 1-hour TTL
  const { data: db } = await client.post(`${mgmt}/v1/redis/databases`, {
    name: "session-cache",
    ttl: "1h",
  });

  console.log(`Redis ready at ${db.url}`);

  // Store session data
  await client.post(`${db.url}/set/session:abc/active`);
  await client.post(`${db.url}/expire/session:abc/3600`);

  // Read it back
  const { data: value } = await client.get(`${db.url}/get/session:abc`);
  console.log("Session:", value.result); // "active"

  // List all databases
  const { data: list } = await client.get(`${mgmt}/v1/redis/databases`);
  console.log(`Total databases: ${list.databases.length}`);

  // Clean up
  await client.delete(`${mgmt}/v1/redis/databases/${db.id}`);
}

await cacheWorkflow();

Fetch

import { createFetch } from "@sapiom/fetch";

const sapiomFetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
  serviceName: "Data Redis",
  agentName: "my-agent",
});

const mgmt = "https://upstash.services.sapiom.ai";

async function cacheWorkflow() {
  // Create a Redis database with 1-hour TTL
  const createRes = await sapiomFetch(`${mgmt}/v1/redis/databases`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name: "session-cache", ttl: "1h" }),
  });

  const db = await createRes.json();
  console.log(`Redis ready at ${db.url}`);

  // Store session data
  await sapiomFetch(`${db.url}/set/session:abc/active`, { method: "POST" });
  await sapiomFetch(`${db.url}/expire/session:abc/3600`, { method: "POST" });

  // Read it back
  const getRes = await sapiomFetch(`${db.url}/get/session:abc`);
  const value = await getRes.json();
  console.log("Session:", value.result); // "active"

  // List all databases
  const listRes = await sapiomFetch(`${mgmt}/v1/redis/databases`);
  const list = await listRes.json();
  console.log(`Total databases: ${list.databases.length}`);

  // Clean up
  await sapiomFetch(`${mgmt}/v1/redis/databases/${db.id}`, { method: "DELETE" });
}

await cacheWorkflow();

Pricing

Operation	Cost
Redis command	$0.000002 per command
Redis pipeline	$0.000002 per command in batch
Vector upsert	$0.000004 per vector
Vector query/fetch/other	$0.000004 per request
Search upsert	$0.00005 per request
Search query	$0.00005 per request
Search query with reranking	$0.00105 per request
Management operations (create, list, get, update, delete)	Nominal

Using Python?

See Service Proxy for REST API access without the Node.js SDK.