Documentazione di VirtualDrive Cloud

Archiviazione a oggetti per sviluppatori e agenti IA. Aggiungi l'archiviazione di file a qualsiasi app in pochi minuti.

Avvio rapido

Crea un progetto nella dashboard, genera una chiave API e poi installa l'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);

Autenticazione

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

Caricare un file

Carica i byte direttamente, oppure richiedi un URL prefirmato per caricamenti grandi o direttamente dal browser.

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

Download e URL firmati

Ogni file può essere distribuito tramite un URL firmato di breve durata. Per impostazione predefinita nulla è pubblico.

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

Elencare ed eliminare

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

Esempi per framework

Alcune integrazioni comuni. Usano tutte l'SDK JS; tieni la chiave lato server.

Next.js — gestore di route

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

Non mettere mai la tua chiave API nel browser. Carica tramite il tuo server (esempi qui sopra), oppure fai restituire al server un URL firmato da usare nel client.

Server MCP

Collega qualsiasi agente IA al tuo spazio di archiviazione tramite il Model Context Protocol. Punta il tuo client MCP all'endpoint ospitato con una chiave di progetto, oppure avvia lo shim locale:

npx @virtualdrive/mcp --key $VD_API_KEY

# Tools exposed: list_files, read_file, write_file, delete_file

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

Webhook

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

Errori e limiti

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.