Getting started

smoldb provides a project-scoped SQLite database and blob storage over HTTP. Each project has a single API key. A first-party MCP server exposes the same API to Claude Desktop and other MCP clients.

Features

  • Tables and rows: typed columns backed by SQLite. List endpoints return at most 100 rows per call.
  • File storage: multipart uploads with per-plan size quotas (50 MB / 500 MB database, 200 MB / 2 GB files).
  • API key: one smol_... key per project, passed via the x-api-key header. Keys are stored hashed and shown once at creation.
  • Rate limits: per-key token bucket (60 req/min free, 600 req/min pro). Over-limit requests return 429.

First project

  1. Sign in at the dashboard and create a project. Record the projectId shown in the URL.
  2. Open the Connect panel and generate an API key. Keys are prefixed with smol_.
  3. Create a table from a terminal: 
    curl -X POST https://your-smoldb.com/api/projects/<projectId>/tables \
  -H "x-api-key: smol_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"todos","columns":[{"name":"title","type":"TEXT"}]}'
  4. Insert a row and read it back with POST and GET /tables/todos/rows. All other endpoints follow the same pattern.

JavaScript SDK

The smoldb-js package provides a chainable client over the HTTP API for JavaScript and TypeScript projects.

import { smoldb } from "smoldb-js";
 
const db = smoldb({
  url: "https://your-smoldb.com",
  projectId: "<projectId>",
  key: "smol_...",
});
 
await db.from("todos").insert({ title: "buy milk" });
 
const { data, error } = await db
  .from("todos")
  .select("*")
  .eq("done", 0);

The guides below use the SDK for JavaScript examples. The curl snippets show the raw HTTP shape.

Next