DataDrift API

Use DataDrift from any browser page.

The DataDrift API exposes a small global object named db. Import the script, set your API key, then create and read values with public OrbitDB and Yjs-backed storage.

Import The API

Add the hosted DataDrift API script before your app code.

<script src="https://datadrift.pages.dev/v1/api.js"></script>

To add G1 cloud storage support, load the G1 addon after the main API script.

<script src="https://datadrift.pages.dev/v1/api.js"></script>
<script src="https://datadrift.pages.dev/v1/g1.js"></script>

If you are testing locally, you can import the local file instead.

<script src="../v1/api.js"></script>

Set Your API Key

Generate a key in the dashboard, then call db.key() once before using the API.

db.key("your-api-key");

Create Records

Use db.create() to store one or more values.

await db.create("users:ada");

await db.create(
  "projects:first-app",
  "settings:theme"
);

The API stores each value under your API key namespace.

Read Records

Use db.read() with the same value you created.

const user = await db.read("users:ada");
const records = await db.read("projects:first-app", "settings:theme");

Reading one value returns one record. Reading multiple values returns an array.

Add-on Auth

Sites can use the official DataDrift API from any origin without an extra DataDrift gate. For example, turbo.com or copilot.net can load https://datadrift.pages.dev/v1/api.js and call db.create() or db.read() normally after setting a DataDrift API key.

The authorization screen is only for add-ons that are loaded from outside https://datadrift.pages.dev. The screen is owned by api.js and shows the add-on script URL, the page origin using it, what the add-on can access, and what it cannot access. Add-ons request permission through the API-level db.__authorize() hook.

<script src="https://datadrift.pages.dev/v1/api.js"></script>
<script src="https://datadrift.pages.dev/v1/g1.js"></script>

db.key("your-api-key");

// Official DataDrift-hosted G1 does not prompt.
const uploads = await db.upload.list();

Use testauth.html to test the flow with a local copied add-on. Its regular API buttons should not prompt, while its G1 add-on buttons should prompt.

G1 Cloud Storage

G1 cloud storage is DataDrift's upload storage system. Load v1/g1.js after v1/api.js to add db.upload(). Calling db.upload("<value>") opens a file picker and uploads the selected files to that Puter folder path. The addon saves upload metadata to public OrbitDB/Yjs storage under your DataDrift API key so pages using the same key can see the same upload index.

<script src="https://datadrift.pages.dev/v1/api.js"></script>
<script src="https://datadrift.pages.dev/v1/g1.js"></script>

db.key("your-api-key");

const uploaded = await db.upload("uploads/profile-images");
console.log(uploaded.path, uploaded.url);

const uploads = await db.upload.list();
console.log(uploads);

By default, uploads create missing folders, deduplicate file names, and allow selecting more than one file. Pass options as the second argument to change Puter upload behavior.

await db.upload("uploads/documents", {
  multiple: false,
  accept: ".pdf",
  overwrite: true
});

Each saved upload record includes name, path, type, size, uploadedAt, and a temporary url when Puter can create one.

DataDrift Auth

DataDrift Auth is a browser DB helper for account systems. It works like the regular DataDrift API, but db.create() can automatically encrypt records before they are stored.

<script src="https://datadrift.pages.dev/v1/auth.js"></script>

db.key("your-api-key");
db.create.encrypt = true;

await db.create("users:ada:password");
const passwordRecord = await db.read("users:ada:password");

When db.create.encrypt is true, DataDrift Auth uses browser Web Crypto AES-GCM encryption and stores the encrypted record in an auth-specific database namespace. Use a unique DataDrift API key for each app that needs a separate account database.

Allowance And Compression

Each API key allows up to 10 million requests per day. A request is counted when you call db.create() or db.read().

DataDrift tracks estimated stored size in the browser. Once a database passes 100 TB, new records are compressed automatically when the browser supports compression streams. Reads decompress those records for you.

Notes

The DataDrift browser key is the secret key. Treat it like a password and do not expose it in public code, screenshots, logs, or shared support messages.

All browser API keys are encrypted for security.

For security, please add your browser key as a secret in your hosting provider.

Beginner Tips

• Call db.key() before every first API call on a page.
• Use clear names like users:123, posts:welcome, or settings:app.
• Wrap API calls in try and catch so you can show helpful error messages.
• Keep your API key private and generate a new one if it is exposed.
• Use the browser console while learning so you can inspect returned values quickly.

try {
  db.key("your-api-key");
  await db.create("hello:data");
  console.log(await db.read("hello:data"));
} catch (error) {
  console.error("DataDrift error:", error.message);
}