Documentatie van VirtualDrive Cloud

Objectopslag voor ontwikkelaars en AI-agenten. Voeg in enkele minuten bestandsopslag toe aan elke app.

Snel starten

Maak een project in het dashboard, genereer een API-sleutel en installeer daarna de SDK:

npm install @virtualdrive/cloud

import { VirtualDrive } from "@virtualdrive/cloud";

const vd = new VirtualDrive(process.env.VD_API_KEY);

const file = await vd.files.upload({ name: "hello.txt", data: "hi!" });
console.log(file.url);

Authenticatie

Every request authenticates with a project API key sent as a Bearer token. Keys are scoped to a single project and a set of permissions (files:read, files:write, files:delete). Keys are shown once at creation — store them as a secret.

Authorization: Bearer vdk_live_xxxxxxxxxxxxxxxx

Een bestand uploaden

Upload de bytes rechtstreeks, of vraag een vooraf ondertekende URL aan voor grote uploads of uploads vanuit de browser.

curl https://api.virtualdrive.cloud/v1/files \
  -H "Authorization: Bearer $VD_API_KEY" \
  -F "name=report.pdf" \
  -F "file=@report.pdf"

Downloads en ondertekende URL's

Elk bestand kan worden uitgeleverd via een kortlevende ondertekende URL. Standaard is niets openbaar.

const { url } = await vd.files.signedUrl(fileId, { expiresIn: 3600 });

Opsommen en verwijderen

const { files } = await vd.files.list({ prefix: "invoices/" });
await vd.files.delete(fileId);

Voorbeelden per framework

Een paar veelgebruikte integraties. Ze gebruiken allemaal de JS-SDK; houd je sleutel aan de serverkant.

Next.js — routeafhandeling

// app/api/upload/route.ts
import { VirtualDrive } from "@virtualdrive/cloud";
const vd = new VirtualDrive(process.env.VD_API_KEY!);

export async function POST(req: Request) {
  const form = await req.formData();
  const file = form.get("file") as File;
  const stored = await vd.files.upload({
    name: file.name,
    data: await file.arrayBuffer(),
    contentType: file.type,
  });
  return Response.json({ url: stored.url });
}

Express

import express from "express";
import { VirtualDrive } from "@virtualdrive/cloud";
const vd = new VirtualDrive(process.env.VD_API_KEY);

app.post("/upload", async (req, res) => {
  const file = await vd.files.upload({ name: req.body.name, data: req.body.data });
  res.json({ url: file.url });
});

Swift (iOS / macOS)

import VirtualDrive

let vd = VirtualDrive(apiKey: ProcessInfo.processInfo.environment["VD_API_KEY"]!)
let file = try await vd.files.upload(name: "photo.jpg", data: imageData, contentType: "image/jpeg")
print(file.url)

Swift Package: add this repo's sdk-swift via Swift Package Manager (iOS 15+ / macOS 12+). Keep the key server-side for shipped apps; use a short-lived key or proxy for clients.

Browser

Zet je API-sleutel nooit in de browser. Upload via je server (voorbeelden hierboven), of laat de server een ondertekende URL teruggeven die de client gebruikt.

MCP-server

Verbind elke AI-agent met je opslag via het Model Context Protocol. Wijs je MCP-client met een projectsleutel naar het gehoste eindpunt, of draai de lokale shim:

npx @virtualdrive/mcp --key $VD_API_KEY

# Tools exposed: list_files, read_file, write_file, delete_file

LLM-readable API summary: /developers/llms.txt

Webhooks

Register an endpoint in the dashboard to receive events: file.uploaded, file.deleted. Each delivery is a POST with an HMAC-SHA256 signature so you can verify it came from us.

// Headers on every delivery:
//   X-VD-Event: file.uploaded
//   X-VD-Signature: sha256=<hex>
// Verify (Node):
import crypto from "crypto";
const sig = "sha256=" + crypto.createHmac("sha256", WHSEC).update(rawBody).digest("hex");
if (sig !== req.headers["x-vd-signature"]) throw new Error("bad signature");

// Body: { "event": "file.uploaded", "created": "...",
//         "data": { "id": "...", "name": "...", "size": 1234 } }

Fouten en limieten

Standard HTTP status codes. 401 invalid key · 403 scope/quota · 413 file too large · 429 rate limited · 503 service paused. Usage is metered per project (stored bytes + requests); a generous free tier is included at launch.