ZiB Network Developer API
DocsS3-compatible encrypted storage with distributed redundancy. Authorization: Bearer <accessKey>:<secretKey>
SDK
/v1/api/upload/initiateapi.zibnetwork.comInitiate Upload
The one upload endpoint for all file sizes. Your server calls this with master credentials — ZiB generates a per-file encryption key and returns a registration object. The browser passes that registration to ZiBStorage.uploadDirect(file, registration) — no credentials ever reach the browser. ZiB automatically chooses the optimal upload path based on file_size: small files use a single encrypted PUT to a storage node; large files use credentialless multipart. The browser call is identical either way — the SDK handles everything transparently. Optionally include a `pipeline` field to declare the full job (encode + transcribe + vision) in the same call — ZiB selects a node that can fulfil every stage AND auto-enqueues the downstream jobs as soon as the file finishes sharding. Poll GET /v1/api/pipeline/{file_id} for unified status.
Body: { "bucket": "my-bucket", "key": "videos/film.mp4", "file_size": 524288000, "pipeline": { "encode": true, "transcription": "fastest"|"recommended"|"accurate", "vision": "standard"|"hq", "webhook_url": "https://...", "webhook_secret": "..." } }. The pipeline field is optional. When omitted, the upload completes and the file is ready — no downstream jobs fire. When present, ZiB selects a node that supports every requested stage and auto-enqueues encoding (with the specified AI tiers) the moment sharding finishes. The legacy `capabilities: ["encode","transcribe","vision"]` array is still accepted for backwards compat but deprecated — prefer `pipeline` going forward. Always call this from your server, never from the browser; master credentials stay on your server.
File (encrypted in browser)
Enter credentials above to run live requests
// Load SDK: <script src="https://app.zibnetwork.com/sdk/zib-sdk.js"></script>
// ─── Step 1: Your server calls ZiB to initiate the upload ──────────────────
// (Node.js / Next.js API route — master credentials stay on the server)
//
// export async function POST(req) {
// const user = await getAuthenticatedUser(req); // your own auth
// if (!user) return Response.json({ error: 'Unauthorized' }, { status: 401 });
//
// const { fileName, fileSize } = await req.json();
// const key = `${user.id}/${Date.now()}-${fileName}`;
//
// const res = await fetch('https://api.zibnetwork.com/v1/api/upload/initiate', {
// method: 'POST',
// headers: {
// 'Content-Type': 'application/json',
// Authorization: 'Bearer ' + process.env.ZIB_ACCESS_KEY + ':' + process.env.ZIB_SECRET_KEY,
// },
// body: JSON.stringify({ bucket: 'my-bucket', key, file_size: fileSize }),
// });
//
// // registration = { type, file_id, upload_url (single) OR upload_id (multipart), ... }
// // (Pass the entire registration object straight to the SDK — internals are opaque.)
// const registration = await res.json();
// return Response.json(registration); // credentials never leave the server
// }
// ─── Step 2: Browser receives registration and calls uploadDirect() ─────────
// No credentials in the browser. Works for any file size — SDK picks single
// PUT or credentialless multipart automatically based on registration.type.
const registration = await fetch('/api/your-initiate-route', {
method: 'POST',
body: JSON.stringify({ fileName: file.name, fileSize: file.size }),
}).then(r => r.json());
const result = await ZiBStorage.uploadDirect(file, registration, {
onProgress: ({ stage, progress }) => console.log(`${stage}: ${progress}%`),
});
console.log('CDN URL:', result.cdn_url);
// => https://cdn.zibnetwork.com/objects/<uuid>
// ─── Step 3: Send file_id back to your server to record the upload ──────────
await fetch('/api/confirm', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ file_id: result.file_id }),
});
// ─── Why this is secure ─────────────────────────────────────────────────────
// ZiB generates the encryption key server-side and stores it. The browser
// encrypts with that key before sending bytes to the node. If someone bypasses
// the SDK and PUTs plaintext, the CDN decrypts with the stored key and returns
// garbage — the file is self-evidently broken. No credentials in the browser
// means no ability to initiate uploads outside this flow either.Recommended: Server-Side Initiation Pattern
Server initiates the upload
Your server calls POST /v1/api/upload/initiate with Authorization: Bearer ACCESS_KEY:SECRET_KEY. ZiB returns a registration object that contains everything the SDK needs to complete the upload. Master credentials never leave your server.
Server returns the registration to the browser
Your server forwards the entire registration object to the authenticated browser. The registration is a one-time upload token — it cannot be used to list buckets, delete objects, or do anything other than complete the specific upload it was created for.
Browser encrypts and uploads via ZiBStorage.uploadDirect()
The browser calls ZiBStorage.uploadDirect(file, registration, { onProgress }). The SDK encrypts the file client-side and sends the ciphertext directly to the assigned storage node. Returns { file_id, cdn_url }.
Browser confirms with your server
The browser sends file_id back to your server so you can record the upload in your database. You now have the cdn_url for serving the file.
Why this is self-enforcing
The encryption key is generated by ZiB and stored server-side. If someone bypasses the SDK and PUTs plaintext bytes, the CDN will decrypt with the stored key and return garbage. There is no way to upload unencrypted content that appears valid — the system enforces encryption without requiring trust in the client.
{
"type": "single",
"file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"cdn_url": "https://cdn.zibnetwork.com/objects/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"upload_url": "https://node.zibnetwork.com/upload/<one-time-token>"
}