ZiB Network

Overview

ZiB is decentralised encrypted storage. Files are encrypted client-side before any bytes leave the browser, split into encrypted chunks and replicated across the storage network, and streamed back on read. Storage nodes never see plaintext — not the file content, not the filename, not the encryption key.

Your tenant credentials (access_key:secret_key) authenticate API calls. ZiB only knows about tenants — you manage your own users and decide who can access what. ZiB never stores user identities.

How It Works

Every file uploaded to ZiB goes through a four-stage pipeline before it is available on the network.

Quick Start

Integrate ZiB storage into your app in five steps. The key architectural rule: credentials stay on your server, the SDK runs in the browser.

<script src="https://app.zibnetwork.com/sdk/zib-sdk.js"></script>

<script src="https://app.zibnetwork.com/sdk/zib-sdk-1.7.2.js"></script>

// Node.js / Next.js App Router
export async function POST(req) {
  // 1. Authenticate with your own system first
  const user = await getAuthenticatedUser(req);
  if (!user) return Response.json({ error: 'Unauthorized' }, { status: 401 });

  const { fileName, fileSize, contentType } = await req.json();

  // 2. Build a scoped object key using your user's ID
  const key = `${user.id}/${Date.now()}-${fileName}`;

  // 3. Call ZiB — credentials stay on the server
  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,
      // Forward the browser's File.type so the CDN can return the
      // correct Content-Type header. Without this, iOS Safari refuses
      // to render <img> tags and OG/social link previews fall back to
      // text-only because the CDN defaults to application/octet-stream.
      content_type: contentType,
    }),
  });

  if (!res.ok) return Response.json({ error: 'Failed to initiate upload' }, { status: 502 });

  const registration = await res.json();

  // 4. Return the registration object — no credentials in here
  return Response.json(registration);
}

// Browser — no credentials here
const registration = await fetch('/api/upload-initiate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    fileName: file.name,
    fileSize: file.size,
    // Pass the browser's MIME type up so the CDN can serve the
    // correct Content-Type — required for <img> tags on iOS Safari
    // and for Open-Graph image unfurling on Slack / Twitter / iMessage.
    contentType: file.type || 'application/octet-stream',
  }),
}).then((r) => r.json());

const result = await ZiBStorage.uploadDirect(file, registration, {
  onProgress: ({ stage, progress }) => {
    console.log(`${stage}: ${progress}%`);
    // stage: 'encrypting' | 'uploading' | 'completing'
  },
});

console.log(result.cdn_url);
// → https://cdn.zibnetwork.com/objects/<uuid>?exp=...&tok=...
// Store file_id, not the URL — see Object URLs.

// Send back to your server to persist
await fetch('/api/save-file', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    file_id: result.file_id,       // stable forever — this is the thing to store
    object_key: key,               // the key you provided at initiate
  }),
}).then((r) => r.json());

// At render time, resolve a URL from the file_id (server-side, Bearer creds):
//   GET /v1/api/object-url?file_id=<file_id>          -> { url, expires_in_seconds }
//   POST /v1/api/object-urls  {"file_ids":[...]}      -> up to 100 at once
// HLS playback is different: /stream/<file_id>/master.m3u8 IS safe to store.

The Upload Flow

Here is what happens under the hood when you call uploadDirect. The key principle: credentials and keys never cross the server/browser boundary.

The registration object

You never have to build any of this yourself — pass the whole object through to uploadDirect() untouched. It's documented here so the fields are recognisable when you're reading a log or debugging a failed upload.

{
  "upload_type":       "multipart",              // always "multipart" — every upload is chunked
  "upload_id":         "d3f1…",                  // the chunked-upload session
  "file_id":           "d3f1…",                  // permanent ID; also the CDN path segment
  "encryption_key":    "<64 hex chars>",         // 32-byte AES-256-GCM key, per file
  "encryption_iv":     "<24 hex chars>",         // 12-byte base IV
  "encryption_scheme": "per-chunk-gcm-v1",       // each 5 MiB chunk sealed separately
  "webtransport": {                              // optional — present only when the assigned
    "host":        "192.168.1.42",               //   node advertises a reachable WT endpoint.
    "port":        4433,                         //   Absent means "use the CF path"; it is a
    "cert_sha256": "<hex>"                       //   hint, never a requirement.
  }
}

SDK Reference

The ZiB SDK is a single browser-side JavaScript file with no dependencies. Load it once via script tag.

<script src="https://app.zibnetwork.com/sdk/zib-sdk.js"></script>

Primary upload method

Reading objects direct from a node

For most reads, just use the CDN URL — it's a plain public URL and works in an <img> or <video> tag with no SDK at all. Reach for fetchObject when you specifically want the bytes to come from a storage node rather than through ZiB's infrastructure.

Account-level operations

For listing, deleting, and encoding, instantiate the class with credentials. These calls should be made from your server, not the browser — credentials are required.

Video encoding

Server-side Integration

The ZiB SDK runs in the browser. For server-side code (Node.js, Python, etc.) call the ZiB API directly with fetch or any HTTP client. All endpoints accept the same Bearer auth format.

Authentication

All authenticated endpoints accept a single header:

Authorization: Bearer <access_key>:<secret_key>

Your access key and secret key are displayed once when you create a storage account. Store them as environment variables (ZIB_ACCESS_KEY, ZIB_SECRET_KEY). No SigV4 signing is required.

Node.js example — initiate + upload

// Server: initiate the upload (credentials stay on your server)
const initRes = await fetch('https://api.zibnetwork.com/v1/api/upload/initiate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bucket: 'my-bucket',
    key: 'videos/intro.mp4',
    file_size: fileBuffer.length,
    content_type: 'video/mp4',  // forwarded to the CDN's Content-Type header
  }),
});
const registration = await initRes.json();
// registration = { upload_type, file_id, upload_url?, upload_id?, ... }
// (Additional opaque fields are returned — pass the entire object straight to the SDK.)

// Return 'registration' to the browser for ZiBStorage.uploadDirect().
// The browser sends the bytes — see "Where the bytes are uploaded from" below.

Python example — list objects

import requests

headers = {"Authorization": f"Bearer {ZIB_ACCESS_KEY}:{ZIB_SECRET_KEY}"}

# List buckets
buckets = requests.get("https://s3.zibnetwork.com/s3/", headers=headers)

# List objects
objects = requests.get("https://s3.zibnetwork.com/s3/my-bucket", headers=headers)

# Start encoding
res = requests.post(
    "https://api.zibnetwork.com/v1/api/encoding/jobs",
    headers={**headers, "Content-Type": "application/json"},
    json={"object_key": file_id, "transcription": "recommended"},
)
job = res.json()  # { encoding_id, status, progress, ... }

Where the bytes are uploaded from

In practice this splits cleanly, and it's the split most tenants want anyway — your credentials stay server-side while the file goes browser → node without a round trip through your infrastructure:

• Your server — authenticates the user, then calls POST /v1/api/upload/initiate and returns the registration to that user's browser. Everything else on this page — triggering encoding, polling status, deleting files, receiving webhooks — is a plain HTTPS call from your backend with Bearer access_key:secret_key.
• The browser — calls ZiBStorage.uploadDirect(file, registration), which encrypts and sends the chunks. This is the only step that must happen client-side.

If a file only ever exists on your server — a batch import, a scheduled job, a file received over an API — there is no supported upload path for it today. Talk to us about the use case rather than attempting to reproduce the encryption wire format; a mis-encrypted upload is accepted at write time and only fails later, when the CDN decrypts it and serves garbage.

Usage and billing reads

Co-located Fast Path (LAN)

When a creator uploads from a browser on the same Wi-Fi as a ZiB Storage Node (typically their own laptop or desktop running the ZiB app with Gateway on), ZiB can route the upload directly to that node over WebTransport / QUIC, bypassing the Cloudflare tunnel entirely. Typical throughput goes from ~1.5 MB/s (residential CF tunnel ceiling) to 30–100 MB/s (LAN speed bounded by AES-GCM + disk write). For off-LAN creators the SDK falls back transparently to the existing multipart-over-CF path — no behaviour change.

When this helps

• A creator uploads from a browser on the same machine (or same Wi-Fi) as a ZiB node they own and run.
• The win scales with file size — every upload is chunked, so even small files take this path, but the saving only becomes noticeable on larger ones.
• Chromium-based browser (Chrome, Edge, Arc, Brave). Safari + Firefox lack WebTransport today and silently fall back.

1. Browser side — probe before initiating

Call ZiBStorage.discoverLocalNode() before asking your server to call /v1/api/upload/initiate. It pings http://localhost:8080/_/ping on the local gateway port and returns the node identity if one is reachable. Resolves in ~300 ms or to null.

// At the top of your upload handler:
const local = await ZiBStorage.discoverLocalNode().catch(() => null);
// local === { node_id: "ZB-XXX", wt_port: 4443 } | null

const res = await fetch('/api/upload-initiate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    bucket,
    key,
    file_size,
    prefer_node: local?.node_id ?? null,   // ← this line
  }),
});
const registration = await res.json();
const result = await ZiBStorage.uploadDirect(file, registration, { onProgress });

The probe is cached per page load — calling it again is free. Pass { force: true } to re-probe (useful if the local node restarted mid-session and may have changed its ID).

2. Server side — forward the hint

In your /api/upload-initiate route, pass prefer_node through to ZiB's /v1/api/upload/initiate:

// app/api/upload-initiate/route.ts (Next.js)
export async function POST(req: Request) {
  const body = await req.json();
  const zibRes = await fetch('https://api.zibnetwork.com/v1/api/upload/initiate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      bucket: body.bucket,
      key: body.key,
      file_size: body.file_size,
      prefer_node: body.prefer_node ?? undefined,   // ← this line
      pipeline: body.pipeline,
      // ...whatever else you already send
    }),
  });
  return new Response(await zibRes.text(), {
    status: zibRes.status,
    headers: { 'Content-Type': 'application/json' },
  });
}

ZiB's selector treats prefer_node as a soft preference — the hinted node wins if it's online and eligible, otherwise the existing free-space / freshness ranking takes over. If the hinted node has zero storage allocated (typical for a desktop ZiB app in transit-only mode) the capacity floor is bypassed too, because the node's shard server still refuses writes if it actually runs out of disk.

3. That's it

No SDK call changes needed. When the chosen node has a WebTransport listener published, the /initiate response now includes an optional webtransport: { host, port, cert_sha256 } field. uploadDirect() reads it automatically, opens a QUIC session pinned via serverCertificateHashes, and streams encrypted chunks LAN-direct. On any failure (off-LAN, UDP blocked, cert mismatch, no WebTransport API) it falls back to the existing multipart path with a diagnostic line in the console.

Browser compatibility & UX hints

The WT path runs in Chromium browsers today (Chrome, Edge, Arc, Brave, Opera). Safari and Firefox fall back silently — the upload still completes correctly over the existing multipart-CF path, just at the slower CF tunnel speed. The fallback prints a single line to the browser console ([ZiB] WebTransport upload unavailable…) but otherwise emits no UI signal. Tenants can optionally surface a hint to creators on fallback browsers so they understand why an upload is taking longer.

// Cheap pre-upload capability detection — no probes, no permissions.
const wtSupported = typeof WebTransport !== 'undefined';
const local = wtSupported
  ? await ZiBStorage.discoverLocalNode().catch(() => null)
  : null;

if (!wtSupported) {
  // Safari / Firefox / older Chromium. Optional UX hint.
  showToast('Tip: uploads are 10–30× faster in Chrome, Edge, or Arc.');
} else if (!local) {
  // Chromium but no co-located ZiB node reachable.
  // Either the creator isn't running a node, or it's on a different network.
  // No hint needed — they're on the normal path.
}

Don't block uploads on the browser check — fallback is a correctness path, not a failure mode. The toast pattern above is purely a courtesy. Most creators will never notice the difference because their upload still completes; the hint just sets expectations for creators who manage their own ZiB nodes and care about peak throughput.

macOS Local Network permission

On macOS Sequoia and later, the first time a browser tries to reach a non-localhost LAN target it triggers a system permission prompt. If the creator dismisses or misses it, that browser will silently fall back to CF tunnel until the user grants permission via System Settings → Privacy & Security → Local Network. The localhost:8080 probe used by discoverLocalNode() is exempt from this rule and always works.

Versions required

• ZiB SDK ≥ 1.7.0 (auto-served from app.zibnetwork.com/sdk/zib-sdk.js).
• ZiB Storage Node ≥ v0.7.80 on the creator's machine.
• ZiB backend ≥ 2026-05-24 deploy (already live in production).

Frequently asked

What if there's no local node? discoverLocalNode() returns null, you pass prefer_node: null, and ZiB picks a node by the existing rules. Upload proceeds over multipart-CF — same as before.

Does this leak the local IP? Only to the browser tab making the upload. The cert hash and WT host live inside the /initiate response that already needs to reach the browser anyway, and the LAN IP is what the node already advertises to peers on the same network.

Encryption guarantees? Identical. The SDK still AES-256-GCM-encrypts every chunk client-side before any byte leaves the browser. The node receives the same encrypted payload regardless of transport — WebTransport is just the pipe.

Upload Pipeline

A pipeline is a tenant-declared chain of stages that should run on a file after upload — encoding (HLS), transcription (SRT/VTT subtitles), and vision analysis (sidecar JSON). Declare the whole chain in a single field on POST /v1/api/upload/initiate and ZiB will (1) route the upload to a storage node that can fulfil every stage and (2) auto-enqueue each downstream stage as soon as the file finishes sharding. You poll a single endpoint — GET /v1/api/pipeline/{file_id} — to track every stage from one place.

Pipeline shape

{
  "encode": true,
  "transcription": "fastest" | "recommended" | "accurate",
  "vision": "standard" | "hq",
  "webhook_url": "https://yourapp.com/api/zib-pipeline-event",
  "webhook_secret": "whsec_..."
}

Every field is optional. Omit a stage to skip it. The webhook fields are also optional — if provided, ZiB fires HMAC-signed events as each stage completes (in addition to the per-file file.ready webhook configured at the customer level).

Available stages

Server-side pattern (recommended)

Declare the pipeline on your server when calling POST /v1/api/upload/initiate. The browser only receives the registration object — it never needs to know what jobs will run.

// server route — e.g. /api/upload-initiate
const res = await fetch('https://api.zibnetwork.com/v1/api/upload/initiate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${ACCESS_KEY}:${SECRET_KEY}`,
  },
  body: JSON.stringify({
    bucket: 'video',
    key: `videos/${contentId}/${videoType}-${Date.now()}-${fileName}`,
    file_size: fileSize,
    pipeline: {
      encode: true,
      transcription: 'recommended',
      vision: 'standard',
      // Thumbnails are ON by default — omit the field for defaults.
      // thumbnails: false  → opt out
      // thumbnails: { poster: { at: '10%' }, sprite: { interval: 5, width: 160 } }
      //                     → override individual fields
      // Vertical aspect-variant renditions for short-form / Shorts feeds.
      // OFF by default — omit the field for none. Current v1 accepts only ["9:16"].
      // aspect_variants: ['9:16']  → enable a 9:16 vertical rendition alongside
      //                              the main HLS. See "Aspect variants" below.
      webhook_url: 'https://yourapp.com/api/zib-pipeline-event',
      webhook_secret: process.env.WEBHOOK_SECRET,
    },
  }),
})

const registration = await res.json()
// Return registration to browser — credentials stay on the server
return Response.json(registration)

Polling pipeline status

Once the upload finishes, poll GET /v1/api/pipeline/{file_id} for the rolled-up status of every stage. The top-level status field advances through queued → uploading → encoding → ai_processing → complete (or failed). Stages that were not requested in the original declaration are returned as null.

{
  "file_id": "a1b2c3d4-...",
  "status": "ai_processing",
  "cdn_url": "https://cdn.zibnetwork.com/objects/a1b2c3d4-...",
  "declared": { "encode": true, "transcription": "recommended", "vision": "standard" },
  "stages": {
    "upload":        { "status": "complete",
                       "phase": "distributed",
                       "replication_safe_at": null },
    "encoding":      { "status": "completed", "encoding_id": "...", "progress": 100,
                       "hls_manifest_url": "https://cdn.zibnetwork.com/...m3u8" },
    "transcription": { "status": "running", "tier": "recommended", "progress": 40,
                       "output_file_id": null },
    "vision":        { "status": "queued", "tier": "standard", "progress": 0,
                       "output_file_id": null }
  },
  "error": null
}

The stages.upload block exposes three fields beyond status:

• phase — finer-grained lifecycle: pending → uploading → distributed → safe (≥3 verified non-originator holders of the object) or cancelled (superseded by re-upload, or admin-cancelled). Authoritative for non-video uploads where there's no encoding job to read from.
• replication_safe_at — ISO timestamp when the file became fully replication-safe. null until the safety sweep flips phase to safe.
• cancelled_reason — present only when phase === 'cancelled'. Tenant-readable string (e.g. "superseded by re-upload to same bucket+object_key").

If stages.upload.phase === 'cancelled', the rolled-up status is forced to failed regardless of downstream stage state — superseded uploads are terminal even if encoding had partially run. Listen for the file.failed webhook event for an out-of-band signal.

Node selection

ZiB picks a storage node that supports every stage in your declaration — if you ask for vision, only nodes that have registered vision capability in the live capability table are eligible. If no online node can fulfil the full pipeline, the request fails with HTTP 503 immediately so you can fall back gracefully. Capability checks are always against the canonical capability registration, never a stale snapshot.

Upload via Node (PIN)

An alternative to the browser upload path. Instead of having the user's browser encrypt and PUT every byte through the network, you generate a single-use PIN that the user enters in their ZiB Node desktop app. The node app reads the file from local disk, encrypts it natively, shards it, and registers the file — all without the browser ever touching the bytes. After completion, your existing pipeline (encoding, transcription, vision) runs identically to a browser upload — the same file.ready and encoding.* webhooks fire on the same webhook URL.

Flow

1. Your server calls POST /v1/api/upload/pin/create with the same params as /upload/initiate (bucket, key, pipeline). Returns { pin, session_id, expires_at }.
2. You display the 3-word PIN to the user (and optionally a QR code).
3. The user opens the ZiB Node desktop app, clicks Upload → Enter PIN, types the PIN, and chooses a file.
4. The node app encrypts + shards the file locally and registers it with the network.
5. Your server polls GET /v1/api/upload/pin/status/{session_id} until status: "complete" (or use the SDK helper below).
6. The same file.ready webhook fires, the encoding pipeline runs as normal, and you receive encoding.complete on your existing webhook URL.

Server: create a PIN

// Server-side only — your master Bearer credentials never reach the browser.
const res = await fetch('https://api.zibnetwork.com/v1/api/upload/pin/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
  },
  body: JSON.stringify({
    bucket: 'video',
    key: 'videos/abc-123/main.mp4',
    pipeline: {
      encode: true,
      webhook_url: 'https://yourapp.com/api/zib-webhook',
      webhook_secret: process.env.ZIB_WEBHOOK_SECRET,
    },
  }),
});

const { pin, session_id, expires_at } = await res.json();
// pin → "mosaic-trinket-blanket"
// session_id → "5a6b862f-9bb6-4c5a-b5f3-df22bb9da959"
// expires_at → "2026-04-10T15:47:03Z"  (20 minutes from creation)

Server: poll for completion

// Poll until phase is 'ready' or 'failed'. The status endpoint returns
// a full lifecycle rollup so you can render byte-level upload progress,
// then encoding %, then analysis %, all from the same poll.
async function waitForCompletion(sessionId, onProgress) {
  while (true) {
    const res = await fetch(
      `https://api.zibnetwork.com/v1/api/upload/pin/status/${sessionId}`,
      {
        headers: { 'Authorization': `Bearer ${ACCESS_KEY}:${SECRET_KEY}` },
      }
    );
    const s = await res.json();

    // Surface live progress to the UI. `phase` walks through:
    //   pending → redeemed → uploading → encoding → analyzing → ready
    // Each phase populates its own sub-block (defensive read with ?? null
    // so you don't break if a future phase is added).
    onProgress?.({
      phase: s.phase,
      uploadPercent:    s.upload?.progress_percent      ?? null,
      encodingPercent:  s.encoding?.progress_percent    ?? null,
      analysisStage:    s.analysis?.current_stage       ?? null,
      transcriptionPct: s.analysis?.transcription_progress ?? null,
      visionPct:        s.analysis?.vision_progress     ?? null,
    });

    if (s.phase === 'ready')   return { file_id: s.file_id };
    if (s.phase === 'failed' || s.phase === 'expired') {
      throw new Error(`Upload ${s.phase}: ${s.error_message ?? 'no detail'}`);
    }

    await new Promise(r => setTimeout(r, 2000));  // poll every 2s
  }
}

Lifecycle phases

The phase field on /pin/status walks through the full upload-and-pipeline lifecycle so a single button can reflect every stage. The legacy status field is still emitted at the top level for backwards compatibility — new integrations should read phase.

Status response shape

{
  // Top-level rollup
  "phase": "encoding",                      // pending | redeemed | uploading | encoding | analyzing | ready | failed | expired
  "status": "uploading",                    // legacy field — keep reading 'phase' instead
  "redeemed_by_node_id": "ZB-899233",
  "file_id": "0c8e3765-9b2b-4a29-82cb-2f1911fe750c",
  "file_size_bytes": 1823450000,
  "error_message": null,
  "expires_at": "2026-04-15T15:47:03Z",

  // Populated while phase === "uploading" (omitted if no progress
  // report has landed in the last 30 seconds — node may have stalled)
  "upload": {
    "bytes_uploaded": 412300123,
    "total_bytes": 1823450000,
    "progress_percent": 22.6
  },

  // Populated when the pipeline declares encode: true
  "encoding": {
    "status": "encoding",                   // queued | encoding | complete | failed
    "progress_percent": 47.3
  },

  // Populated when the pipeline declares transcription and/or vision.
  // current_stage tracks the slowest path so a single bar reflects the
  // overall analysis progress.
  "analysis": {
    "current_stage": "transcription",       // "transcription" | "vision"
    "transcription_status": "running",      // null if not declared
    "transcription_progress": 42,           // 0–100, null if not declared
    "vision_status": "queued",              // null if not declared
    "vision_progress": 0                    // 0–100, null if not declared
  }
}

Node operator UX (optional context)

When the user enters your PIN in their ZiB Node app, the app shows a capability checklist comparing what your pipeline needs (encode / transcribe / vision) against what their node can do locally. Your tenant_settings.compute_mode setting controls what happens when their node can't do everything:

Video Encoding

After uploading a video file, call startEncoding(fileId) to trigger transcoding. ZiB produces an adaptive HLS stream with multiple quality variants, encrypts every segment, and distributes the segments redundantly across the storage network.

Encoding pipeline

Playback

The output is a standard HLS stream that plays in any HLS-capable player (hls.js, Video.js, native Safari, AVPlayer, etc.). The CDN serves the master manifest and per-quality variant playlists at predictable URLs — the player handles encryption and adaptive bitrate switching automatically.

Triggering encoding

// After uploadDirect() completes, pass file_id to startEncoding
const job = await storage.startEncoding(result.file_id);
console.log(job.encoding_id); // use this to poll status

// Poll until complete
const status = await storage.getEncodingStatus(job.encoding_id);
// status.hls_manifest_url — AES-128 encrypted HLS, plays in any HLS player

Tracking encoding progress

Poll for this — there is no progress webhook. This page previously described an encoding.progress event throttled to 10s / 5% deltas. It is not emitted. Nothing in the backend fires it, so a UI driven from it sits at 0% from encoding.started until encoding.complete and never errors. Use GET /v1/api/pipeline/{file_id} instead: it returns a 0–100 integer for the encode stage and works for every stage of the pipeline, not just encoding.

The payload carries a progress integer (0–100) and a stage field ("encoding" or "sharding") so you can optionally show which phase the job is in. The percentage is continuous across both phases — you don't need to track them separately.

// Webhook handler — store the progress value, render in your UI
app.post('/api/zib-webhook', (req, res) => {
  const { event, file_id, progress, stage } = req.body;

  if (event === 'encoding.progress') {
    // progress is an integer 0–100
    // stage is "encoding" or "sharding"
    await db.update('videos', { encoding_progress: progress }, { where: { file_id } });
  }

  if (event === 'encoding.complete') {
    // Final state — manifest URLs are now live
    await db.update('videos', {
      encoding_progress: 100,
      encoding_status: 'complete',
      hls_url: req.body.hls_manifest_url,
    }, { where: { file_id } });
  }

  res.sendStatus(200);
});

Polling encoding status correctly

If you can't accept webhooks (or want a fallback alongside them), poll GET /v1/api/pipeline/<file_id> or GET /v1/api/encoding/jobs/<encoding_id> with a small interval (2–5 seconds). Four things to get right:

1. Null-guard the response. Between the moment your /v1/api/encoding/request returns and the moment the encoding job row materialises (typically <1 s), the poll endpoint can return an empty body. Use result?.phase, not result.phase — otherwise your first poll throws a TypeError.
2. Null-guard the closure inputs, too. If your interval/setTimeout captures variables that may flip to null (React state on rapid navigation, a cleared store), check them on every tick — not just at setup. A common shape: if (!content?.id) return; as the first line of the interval callback. A closure that was alive when the fetch was scheduled can fire after the component unmounts or refetches, with stale references that have since been cleared. If you have more than one poller in the same file, make sure every one has the guard — it's easy to add it to the obvious one and miss a sibling that takes the same code path.
3. Stop on the terminal top-level status. GET /v1/api/pipeline/{file_id} returns a top-level status — poll that, not a per-stage field:
   • status === 'complete' — success. HLS manifest is live; use data.cdn_url.
   • status === 'failed' — terminal failure. Read data.error; show a Retry button.
   • In-progress values are queued | uploading | encoding | ai_processing — keep polling.
   To detect a re-upload that superseded this file, check data.stages?.upload?.phase === 'cancelled' and switch your UI to the new file_id.
4. On /pipeline, use the top-level status. The /pipeline/{file_id} rollup exposes status at the top level and a phase only on stages.upload — there is no stages.encoding.phase, and status never returns safe. (The phase vocabulary — safe, failed_user_action — belongs to a different endpoint, GET /v1/api/my-jobs.)
5. Backoff sensibly. 2–5 second poll intervals are plenty. Encoding takes seconds to minutes; tighter polling just burns your rate-limit budget without changing the outcome.

async function waitForEncode(fileId, { timeoutMs = 10 * 60_000, intervalMs = 3_000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(`https://api.zibnetwork.com/v1/api/pipeline/${fileId}`, {
      headers: { Authorization: `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}` },
    });
    if (!res.ok) {
      // Transient network / backend error — log and retry next tick.
      await sleep(intervalMs);
      continue;
    }
    const data = await res.json();

    // 1. Null-guard: the /pipeline rollup may be sparse during the brief
    //    window between the initiate call and the job row being created.
    const status = data?.status;   // top-level rollup status
    if (!status) {
      await sleep(intervalMs);
      continue;
    }

    // 2. Terminal: success. The HLS manifest is live.
    if (status === 'complete') {
      return { ok: true, manifestUrl: data.cdn_url };
    }

    // 3. Terminal: failure.
    if (status === 'failed') {
      return { ok: false, error: data.error ?? 'Encoding failed' };
    }

    // 4. Superseded by a re-upload to the same (bucket, key)?
    //    /pipeline maps 'cancelled' to failed at the top level, so detect
    //    supersede via the upload stage's own phase.
    if (data?.stages?.upload?.phase === 'cancelled') {
      return { ok: false, error: 'Upload superseded; check for the new file_id' };
    }

    // In-progress: queued | uploading | encoding | ai_processing — keep polling.
    await sleep(intervalMs);
  }
  return { ok: false, error: 'Timed out waiting for encode' };
}

const sleep = ms => new Promise(r => setTimeout(r, ms));

Webhooks are still the preferred path — your server doesn't pay for the polling round-trips and you react instantly when the state changes. Polling is the right tool when your environment can't accept inbound HTTPS (a background worker, a CLI script, a deployment behind a firewall without an ingress).

Playing the stream

<!-- hls.js (browser) -->
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="video" controls></video>
<script>
  const hls = new Hls();
  hls.loadSource('https://cdn.zibnetwork.com/stream/<file_id>/master.m3u8');
  hls.attachMedia(document.getElementById('video'));
</script>

<!-- Native HLS (Safari / iOS) -->
<video controls src="https://cdn.zibnetwork.com/stream/<file_id>/master.m3u8"></video>

Re-encoding the same file

POST /v1/api/encoding/request is idempotent. If you request encoding for a file_id that already has a completed encoding job whose segments are live on the CDN, ZiB will not start a second encode — you get back the existing job's ID and CDN URL so your code can carry on as if it had just queued one:

// Response when the file is already encoded
{
  "encoding_id": "771a1e5e-5e29-470a-9f1f-5ad8b999efc4",
  "status": "already_encoded",
  "file_id": "01846192-315c-4f0a-b766-12b18a26b209",
  "cdn_url": "https://cdn.zibnetwork.com/stream/01846192-315c-4f0a-b766-12b18a26b209/master.m3u8",
  "message": "File is already encoded by an existing job. Pass { \"force\": true } in the request body to deliberately re-encode."
}

The same shape applies while a job is mid-flight: you get status: "already_queued" with the in-flight job's ID. Branch on status to decide whether to poll progress, fire your own "already done" UI, or just record the encoding_id and move on.

Forcing a re-encode

When you genuinely want a fresh encode of the same source bytes (changed encoding presets, repaired segments, etc.) pass force: true in the request body:

await fetch('https://api.zibnetwork.com/v1/api/encoding/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${ZIB_ACCESS_KEY}:${ZIB_SECRET_KEY}`,
  },
  body: JSON.stringify({
    object_key: fileId,        // existing file_id
    force: true,               // override the idempotency gate
    webhook_url: WEBHOOK_URL,  // optional
  }),
});

Thumbnails

Every encode produces a poster frame and a WebVTT-driven sprite sheet for scrub-bar previews. Default poster is grabbed at 10% of duration (clamped to 1–10s) so cold-opens and fade-ins don't become the cover image. Default sprite cadence is one tile every 5 seconds at 160px wide, packed into 10×10 grid JPEGs — the WebVTT references each tile with #xywh=x,y,w,h so Bitmovin, hls.js, Video.js and shaka-player pick it up natively. Defaults are ON; pass thumbnails: false to opt out.

// All four shapes are valid on POST /v1/api/encoding/request:

// 1. Omit the field — thumbnails generated with defaults.
{ object_key: fileId }

// 2. Explicit defaults.
{ object_key: fileId, thumbnails: true }

// 3. Opt out entirely.
{ object_key: fileId, thumbnails: false }

// 4. Override individual fields (any subset; missing keys fall back to defaults).
{
  object_key: fileId,
  thumbnails: {
    poster: { at: "10%" },            // or "5s" / "Ns" for an absolute timestamp
    sprite: { interval: 5, width: 160 }
  }
}

When thumbnails are produced, the thumbnails object is surfaced in three places — identical shape on each, so tenants who can't receive webhooks (localhost dev, replayed deliveries, missed events) can still pick the URLs up by polling:

• The encoding.complete webhook payload (top-level field).
• GET /v1/api/pipeline/{file_id} → stages.encoding.thumbnails.
• GET /v1/api/encoding/jobs/{encoding_id} → thumbnails (top-level).

The field is omitted (or null) until the encoder has registered the artifacts — typically a few seconds after phase reaches local_complete. Tenants who opt out (thumbnails: false) will see it stay null forever; that's the contract.

// thumbnails block — same shape on webhook + both polling endpoints.
// Omitted (or null) when the tenant opted out or before registration completes.
{
  "thumbnails": {
    // URLs are signed and expire. Use them now; do not store them.
    "poster_url":         "https://cdn.zibnetwork.com/objects/<uuid>?exp=...&tok=...",
    "sprite_url":         "https://cdn.zibnetwork.com/objects/<uuid>?exp=...&tok=...",
    "sprite_vtt_url":     "https://cdn.zibnetwork.com/objects/<uuid>?exp=...&tok=...",
    // Ids are stable forever. THESE are what you persist.
    "poster_file_id":     "<uuid>",
    "sprite_file_id":     "<uuid>",
    "sprite_vtt_file_id": "<uuid>"
  }
}

Use poster_url directly as the <video poster="..."> attribute or as the cover image in any thumbnail grid. The sprite-sheet VTT plugs into the major HLS players verbatim:

// Bitmovin
player.load({
  hls: hlsManifestUrl,
  poster: thumbnails.poster_url,
  tracks: {
    thumbnailTrack: {
      file: thumbnails.sprite_vtt_url
    }
  }
});

// hls.js — load the VTT yourself and feed it to your seekbar component:
const vtt = await fetch(thumbnails.sprite_vtt_url).then(r => r.text());
// Each cue body is "<sprite_sheet_url>#xywh=x,y,w,h" — render that tile into your scrubber.

// Video.js (vtt-thumbnails plugin)
player.vttThumbnails({ src: thumbnails.sprite_vtt_url });

Aspect variants

Generate a vertical 9:16 HLS rendition alongside the main horizontal encode — for Shorts shelves, TikTok-style vertical feeds, iPhone portrait playback. Each rendition is a full multi-bitrate HLS ladder with its own poster, content-encrypted with a per-rendition AES-128 key, and served from its own CDN stream URL. Defaults are OFF; opt in by passing aspect_variants: ["9:16"]. v1 accepts only 9:16; the field is an array so adding 4:5 / 1:1 / 4:3 later is a non-breaking extension.

The rendition is produced with a center crop (no smart-crop in v1) and an adaptive ladder derived from your source — rungs whose bitrate would exceed the source's are dropped automatically, so a 720p source produces a 720p-and-below vertical ladder, not an upscaled 1080p one.

// 1. Inline mode — declared at upload time, runs alongside the main encode.
//    Add to the same `pipeline` block you pass to /v1/api/upload/initiate.
{
  bucket: 'video',
  key: 'videos/abc.mp4',
  file_size: 1234567,
  pipeline: {
    encode: true,
    aspect_variants: ['9:16'],          // ← new
    webhook_url: 'https://...',
    webhook_secret: process.env.WEBHOOK_SECRET,
  }
}

// 2. Inline mode via /v1/api/encoding/request (same root-level field).
{ object_key: fileId, aspect_variants: ['9:16'] }

// 3. Backfill mode — produce variants for a file that already has a complete
//    horizontal encode, WITHOUT re-running the main pass. Cheaper than force:true.
{ object_key: fileId, aspect_variants_only: ['9:16'] }
//
// Response: { status: 'queued', mode: 'aspect_variants_only',
//             parent_encoding_job_id: '...', child_encoding_job_ids: ['...'] }
//
// Mutually exclusive with force:true and with aspect_variants on the same call.

Once each variant is registered, the aspect_variants object is surfaced in the same three places as thumbnails — keyed by ratio string:

• The encoding.complete webhook payload (top-level field).
• GET /v1/api/pipeline/{file_id} → stages.encoding.aspect_variants.
• GET /v1/api/encoding/jobs/{encoding_id} → aspect_variants (top-level).

Each ratio entry is omitted from the object entirely until the encoder has registered it (typically a few seconds after the main encode reaches local_complete). If a variant encode fails the ratio is simply absent from the response; the parent encode still completes. The entire aspect_variants field is omitted when the tenant didn't opt in.

// aspect_variants block — same shape on webhook + both polling endpoints.
{
  "aspect_variants": {
    "9:16": {
      "hls_manifest_url": "https://cdn.zibnetwork.com/stream/<vertical_file_id>/master.m3u8",
      "poster_url":       "https://cdn.zibnetwork.com/objects/<vertical_poster_id>"
    }
  }
}

The hls_manifest_url is a standard HLS stream — point any player at it the same way you would the horizontal manifest. The vertical rendition has its own file_id and its own AES-128 key (served from /stream/<vertical_file_id>/key), so it's independently routable, cacheable, and replaceable without touching the main encode.

// Bitmovin — switch between horizontal and vertical based on viewport
const horizontal = encodingResult.hls_manifest_url;
const vertical   = encodingResult.aspect_variants?.['9:16']?.hls_manifest_url;
const verticalPoster = encodingResult.aspect_variants?.['9:16']?.poster_url;

player.load({
  hls: window.innerHeight > window.innerWidth ? (vertical || horizontal) : horizontal,
  poster: window.innerHeight > window.innerWidth
    ? (verticalPoster || encodingResult.thumbnails?.poster_url)
    : encodingResult.thumbnails?.poster_url,
});

// React Native / iOS-native — pick the vertical rendition directly for a portrait feed.
const shortsUrl = videoRow.aspect_variants?.['9:16']?.hls_manifest_url;
if (shortsUrl) {
  // Render a vertical scrolling feed using AVPlayer / ExoPlayer.
}

Pattern A — webhook-triggered encode

For the standard tenant upload flow, you typically kick off encoding the moment ZiB delivers file.ready. The shape below is what we recommend for any handler that receives file.ready and decides to start an encode. The idempotency check at step 3 is the most important part — duplicate webhook deliveries should be cheap no-ops, not double-fires.

// app/api/zib-file-ready/route.ts (Next.js App Router style)

export async function POST(req: Request) {
  const event = await req.json();

  // 1. Verify the webhook signature (mandatory — see Webhooks).
  if (!verifyZibSignature(req.headers.get('x-zib-signature'), event)) {
    return new Response('invalid signature', { status: 401 });
  }

  if (event.event !== 'file.ready') {
    return Response.json({ received: true, ignored: true });
  }
  const { file_id, bucket, object_key } = event;

  // 2. Look up your local row by the STABLE identifier — (bucket, object_key).
  //
  //    Do NOT look up by file_id. A re-upload to the same key produces a
  //    NEW file_id, so the row you stored against the prior file_id will
  //    not match and your handler will silently no-op while the user's
  //    UI sits at "Queued — waiting for an encoder" forever.
  const creative = await db.creatives.findUnique({
    where: { bucket_object_key: { bucket, object_key } },
  });
  if (!creative) return Response.json({ received: true, matched: false });

  // 3. Idempotency keyed on file_id — NOT on encoding_status.
  //
  //    - If creative.zib_file_id === event.file_id and we already stored an
  //      encoding_id for it, this is a duplicate webhook delivery → skip.
  //    - If they differ, the user re-uploaded. The stored encoding belongs
  //      to the OLD file and is now cancelled by ZiB; we must fire a fresh
  //      encoding request for the NEW file_id.
  //
  //    A common bug — and the one that causes "Queued forever" deadlocks —
  //    is keying this check on `encoding_status !== 'ERROR'`. That returns
  //    "already handled" for every re-upload whose previous encode succeeded,
  //    so the new upload is never encoded. The user sees their re-upload
  //    "queued" indefinitely and ZiB never receives an encoding request.
  if (creative.zib_file_id === file_id && creative.zib_encoding_id) {
    return Response.json({ received: true, matched: true, deduped: true });
  }

  // 4. Fire encoding request. ZiB is also idempotent server-side — if
  //    another code path already fired for this file_id you'll receive
  //    status: 'already_queued' (in-flight job exists) or
  //    status: 'already_encoded' (completed job exists). Treat both the
  //    same — record the encoding_id and trust webhooks for the rest.
  const res = await fetch('https://api.zibnetwork.com/v1/api/encoding/request', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
    },
    body: JSON.stringify({
      object_key,                 // stable key — NOT file_id
      bucket,
      // webhook_url and webhook_secret are optional here — if you've
      // configured them once on your customer profile, ZiB uses those.
    }),
  });
  if (!res.ok) {
    return new Response(`ZiB encode request failed: ${res.status}`, { status: 502 });
  }
  const job = await res.json();

  // 5. Persist the new file_id AND the new encoding_id together. Writing
  //    file_id is the critical step that lets future webhook deliveries
  //    recognise this row as up to date — without it, the next file.ready
  //    for this key will look like another re-upload and you'll loop.
  await db.creatives.update({
    where: { id: creative.id },
    data: {
      zib_file_id:     file_id,                  // overwrite prior file_id
      zib_encoding_id: job.encoding_id,
      cdn_url:         job.cdn_url ?? job.hls_manifest_url ?? null,
      encoding_status:
        job.status === 'already_encoded' ? 'COMPLETE' : 'ENCODING',
    },
  });

  return Response.json({
    received: true,
    matched: true,
    encoding_id: job.encoding_id,
    status: job.status,
  });
}

Pattern B — user-triggered re-encode

For a "Re-encode" button in your own UI (encoder settings changed, source corrupted, etc.), the call shape is the same plus force: true. The three things you MUST add on your side — none of which ZiB can enforce for you — are: auth on the endpoint, authorization (the caller owns the content), and a server-side dedup check against your own DB. The UI's in-flight lock is not enough; a page reload or a second tab bypasses it.

// app/api/re-encode/route.ts

import { getServerSession } from '@/lib/auth';

export async function POST(req: Request) {
  // 1. Authentication. Refuse anonymous callers.
  const session = await getServerSession(req);
  if (!session?.user) {
    return new Response('unauthenticated', { status: 401 });
  }

  const { content_id, video_type } = await req.json();
  //    video_type: 'main' | 'trailer'

  // 2. Authorization. Caller must own this content (or be admin).
  const content = await db.content.findUnique({ where: { id: content_id } });
  if (!content) return new Response('not found', { status: 404 });
  if (content.owner_id !== session.user.id && !session.user.isAdmin) {
    return new Response('forbidden', { status: 403 });
  }

  const statusKey = `${video_type}_encoding_status`;
  const idKey     = `${video_type}_zib_encoding_id`;
  const fileKey   = `${video_type}_source_file_id`;

  // 3. Server-side dedup. Refuse if an encode is already in flight for
  //    this content+video_type. The UI lock isn't enough — page reload
  //    clears it, a second tab bypasses it, a scripted POST loop wouldn't
  //    even render the UI.
  if (['QUEUED', 'ENCODING'].includes(content[statusKey])) {
    return Response.json(
      { error: 'already_in_progress', encoding_id: content[idKey] },
      { status: 409 },
    );
  }

  // 4. Fire ZiB with force=true. The old encoded segments keep serving
  //    the CDN URL until the new encode completes, so playback isn't
  //    interrupted. Do NOT delete the prior encoded data first — that
  //    creates a window where the file has no playable output if the
  //    new encode never starts (e.g. ZiB returns an error). Let ZiB
  //    do the cutover atomically once segments land.
  const res = await fetch('https://api.zibnetwork.com/v1/api/encoding/request', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
    },
    body: JSON.stringify({
      object_key: content[fileKey],
      force: true,
    }),
  });
  if (!res.ok) {
    return new Response(`ZiB encode request failed: ${res.status}`, { status: 502 });
  }
  const job = await res.json();

  // 5. Record new encoding_id. The cdn_url field on your record does
  //    NOT change — the CDN URL is keyed by file_id, not encoding_id.
  await db.content.update({
    where: { id: content_id },
    data: {
      [idKey]: job.encoding_id,
      [statusKey]: 'ENCODING',
    },
  });

  return Response.json({
    encoding_id: job.encoding_id,
    status: job.status,
  });
}

Viewer Telemetry

Opt-in browser feature for video tenants. The SDK observes HLS segment fetches via the PerformanceObserver API, batches per-segment timings (TTFB, total duration, transfer size), and posts them to ZiB. The backend fuses them with synthetic and peer-node probes into a per-(node, viewer-region) fitness score that quarantines slow nodes from the segment-holder picker — so a CF colo that's silently routing slowly to one part of the world stops being handed to viewers there.

What gets sent

• node_id — the ZB-XXXXXX ID parsed from each segment URL hostname (zb-*.zibnetwork.com)
• ttfb_ms, total_ms, size_bytes from the browser's resource timing entry
• An ephemeral random viewer_session_id (UUID) for throttling — never tied to a wallet, account, or persistent identifier
• The viewer's CF colo (e.g. SYD, LHR) inferred server-side from CF-Ray

No URLs, no IP, no user agent, no cookies. Data is pruned after 24 hours and never leaves ZiB's own infrastructure.

Quickest integration — one line

If your player is a vanilla <video src=".m3u8"> or simple hls.js setup with workers disabled, just call the static helper once on page load. Telemetry observes Resource Timing in the background and flushes on pagehide.

<script src="https://app.zibnetwork.com/sdk/zib-sdk.js"></script>
<script>
  // Anywhere on a watch page, after the SDK script loads.
  // Idempotent — calling twice is harmless.
  ZiBStorage.startTelemetry();
</script>

recordFetch() — the explicit per-segment API

Hook your player's per-segment download event and pass the URL + timing to ZiBStorage.recordFetch(). The SDK parses the node id from the URL, batches the sample, and ships it through the same flush pipeline. No prior startTelemetry() call required — the first recordFetch() lazily initialises the singleton.

// === bitmovin player (8.x — verified against 8.241.0) ===
// IMPORTANT: use SegmentRequestFinished, not SegmentPlayback.
//   - SegmentPlayback fires when a segment starts playing (no timing data)
//   - SegmentRequestFinished fires after download with downloadTime,
//     timeToFirstByte, size, success, httpStatus, url
//
// SegmentRequestFailed does NOT exist in 8.x — failures arrive on
// Finished with event.success === false. httpStatus === 0 means network
// error / CORS reject / abort.
//
// Time units: bitmovin's TypeScript type doc says seconds for downloadTime
// and timeToFirstByte. Multiply by 1000 to get ms. Verify against the DB
// once samples flow — if avg ttfb_ms ends up in the 50,000+ range, the
// runtime actually emitted ms and the multiplier should be removed.
player.on(bitmovin.player.PlayerEvent.SegmentRequestFinished, (event) => {
  // Clamp the -1 "cancelled before headers" sentinel.
  const ttfbSec = Math.max(0, event.timeToFirstByte || 0);
  ZiBStorage.recordFetch({
    url: event.url,
    ttfb_ms: Math.round(ttfbSec * 1000),
    total_ms: Math.round((event.downloadTime || 0) * 1000),
    size_bytes: event.size || 0,
    status: event.success === false
      ? (event.httpStatus === 0 ? 'network_error' : String(event.httpStatus))
      : (event.httpStatus ? String(event.httpStatus) : '200'),
  });
});

// === hls.js (any version) ===
hls.on(Hls.Events.FRAG_LOADED, (_, data) => {
  const stats = data.frag.stats || data.stats;  // hls.js v1 vs v0 paths
  ZiBStorage.recordFetch({
    url: data.frag.url,
    ttfb_ms: Math.round(stats.tfirst - stats.trequest),
    total_ms: Math.round(stats.tload - stats.trequest),
    size_bytes: stats.total,
    status: '200',
  });
});

// === shaka player ===
player.addEventListener('downloadcompleted', (event) => {
  ZiBStorage.recordFetch({
    url: event.request.uris[0],
    ttfb_ms: Math.round(event.response.headers['x-firstbyte-ms'] || event.response.timeMs),
    total_ms: Math.round(event.response.timeMs),
    size_bytes: event.response.data.byteLength,
    status: '200',
  });
});

Samples whose URL doesn't match zb-XXXXXX.zibnetwork.com are silently dropped — without a node identifier in the URL there is nothing to attribute. Pass node_id directly if you have it from another source. Errors are reported with status: 'timeout' or 'network_error'.

attachToVideo() — universal element-level fallback

For coverage that works regardless of player or fetching architecture — including Safari native HLS where neither PerformanceObserver nor a Worker hook is available — attach to the <video> element directly. The SDK reports stalls (waiting → playing transitions), frame drops (via getVideoPlaybackQuality()), and playback errors. File-correlated, not per-segment; the backend resolves to nodes via segment_holders at sample time.

// On player init, after the <video> element is in the DOM
const detach = ZiBStorage.attachToVideo(videoEl, { fileId: '<file-uuid>' });

// On player teardown
detach();

Transport & CORS — what the SDK sends, what the API accepts

The SDK posts samples to POST https://api.zibnetwork.com/v1/api/telemetry/segment-fetch on a 5-second flush timer and one final pagehide flush via navigator.sendBeacon(). The endpoint accepts both transports — the responses are equivalent. You don't need to configure anything for this to work; the notes below exist for tenants who are debugging from DevTools and want to know what to expect.

Inside an existing SDK instance

If you already construct ZiBStorage on the player page, opt in via the constructor option. Same effect; no second include needed.

const zib = new ZiBStorage({
  accessKey: '...',
  secretKey: '...',
  telemetry: { enabled: true },   // <-- one extra option
});

// Optional — bring your own session ID if you already have one
// (e.g. tied to a playback session in your analytics).
new ZiBStorage({
  accessKey: '...',
  secretKey: '...',
  telemetry: { enabled: true, viewerSessionId: '...' },
});

React / Next.js — mount in the root layout

Drop the SDK <Script> and a small client wrapper into your root app/layout.tsx — not a route-group layout like app/(app)/layout.tsx. Route-group layouts only cover routes inside that group; the root layout covers everything.

// app/layout.tsx — Server Component is fine
import Script from 'next/script';
import { ZiBTelemetry } from '@/components/ZiBTelemetry';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {/* Loads on every page; next/script dedupes by src so it's safe to
            keep any per-page <Script> tags in upload flows that need a hard
            guarantee the SDK is present. */}
        <Script src="https://app.zibnetwork.com/sdk/zib-sdk.js" strategy="afterInteractive" />
        <ZiBTelemetry />
        {children}
      </body>
    </html>
  );
}

// components/ZiBTelemetry.tsx — small client wrapper
'use client';
import { useEffect } from 'react';

export function ZiBTelemetry() {
  useEffect(() => {
    let tele: { stop: () => void } | undefined;
    let cancelled = false;

    // Poll for the SDK global — handles the race where <Script
    // strategy="afterInteractive"> hasn't finished loading yet.
    const tick = () => {
      if (cancelled) return;
      // @ts-ignore — global injected by the SDK <script>
      const ZiBStorage = (window as any).ZiBStorage;
      if (ZiBStorage?.startTelemetry) {
        tele = ZiBStorage.startTelemetry();
        return;
      }
      setTimeout(tick, 100);
    };
    tick();

    return () => {
      cancelled = true;
      tele?.stop();   // fires final navigator.sendBeacon flush
    };
  }, []);

  return null;
}

That's the entire integration for any Next.js App Router app. Pages Router is the same idea — drop the <Script> and <ZiBTelemetry /> into pages/_app.tsx instead.

Common placement traps

• Route-group layout (app/(app)/layout.tsx) — covers only that group. Marketing/landing pages, content-detail pages, public preview surfaces typically live in a different group and would miss telemetry. Mount in the root layout instead.
• Single watch route (app/watch/[slug]/page.tsx) — covers exactly one route. Trailers, embed players, hover previews on other routes go uninstrumented.
• Edit-mode-only mount — gating the SDK <Script> behind an isEditMode flag (common in CMS-like rite3 setups) means viewers never load it. Either ungate, or mount in the root layout where the gate doesn't apply.

How to verify it's working

1. Test on at least two different player surfaces — e.g. a watch page and a content-detail page that plays a trailer. If telemetry only fires on one, your mount is too narrow (route-group layout instead of root layout) — see the placement traps above.
2. Open DevTools → Network and filter for zib-sdk.js. The script should load on every page where you expect telemetry, including non-player pages that share the same root layout.
3. Switch the filter to telemetry and play a video for ~30 s. You should see a POST to /v1/api/telemetry/segment-fetch every 30 s or every 10 segments, returning { accepted: <n>, rejected: 0 }. Confirm the segments themselves are coming from zb-*.zibnetwork.com hostnames in the Domain column — that's the URL pattern the SDK matches.
4. Close the tab. The SDK fires a final navigator.sendBeacon on pagehide; that flush still shows up in DevTools' Network panel under Show navigation requests.
5. If you have admin access, your samples land in /superadmin/network within ~60 s, tagged with the appropriate CF colo region (SYD, LHR, etc.) rather than the synthetic-probe sentinel _backend.

Diagnose by response shape

The /v1/api/telemetry/segment-fetch response shape tells you exactly which channels are wired and which are missing. Click any telemetry POST in DevTools → Response and read both fields:

The third row — accepted: 0, playback_events_accepted: N — is by far the most common partial-integration state. attachToVideo is a 2-line addition while the player-event hook needs the integrator to know their player's event API; tenants tend to ship the easy one first and forget the other. Both are needed for full coverage.

Webhooks

ZiB sends signed POST requests to your configured webhook URL when files, encoding jobs, and AI jobs change state.

Configuration patterns

There are three valid ways to consume ZiB lifecycle events. Pick the one that matches how your integration is operated:

Pattern precedence when more than one is configured: per-request body fields always win over tenant-level defaults. Polling can be combined with either of the other two as belt-and-braces.

Common pitfall: if your code assumes tenant-level config is set but the operator clears it (or never set it), encoding requests still succeed but no webhooks fire — silent breakage. Pattern 1 avoids this entire class by carrying config in every request.

Headers

Every webhook request carries:

Content-Type:    application/json
X-ZiB-Event:     <event name>            e.g. encoding.complete
X-ZiB-Job-ID:    <uuid>                  on encoding.* and {transcription,vision}.complete
X-ZiB-Signature: sha256=<hex>            HMAC-SHA256 over the raw request body

Events

Payload shapes

Each event has its own envelope. All payloads include a top-level event string and timestamp (ISO 8601 UTC).

// file.ready — fired the moment shard count reaches the redundancy target
{
  "event":       "file.ready",
  "file_id":     "a1b2c3d4-...",
  "bucket":      "my-bucket",
  "object_key":  "videos/2026-04/film.mp4",
  "size_bytes":  524288000,
  "customer_id": "c0ffee...",
  "timestamp":   "2026-04-08T17:30:00.000Z"
}

// encoding.queued | encoding.started | encoding.sharding | encoding.complete | encoding.failed
// All five share the same shape — only the "event" and "status" fields change.
{
  "event":               "encoding.complete",
  "job_id":              "<encoding_jobs.id>",
  "status":              "complete",          // queued | encoding | sharding | complete | failed
  "file_id":             "a1b2c3d4-...",
  "customer_id":         "c0ffee...",
  "hls_manifest_url":    "https://cdn.zibnetwork.com/stream/<file_id>/master.m3u8",  // null until "complete"
  "error_message":       null,                // populated on "failed"
  "transcription_model": "recommended",       // null if transcription not requested
  "vision_model":        "standard",          // null if vision not requested
  "thumbnails": {                              // null if tenant opted out; see "Thumbnails" above
    "poster_url":     "https://cdn.zibnetwork.com/objects/<poster_file_id>",
    "sprite_url":     "https://cdn.zibnetwork.com/objects/<first_sprite_sheet_file_id>",
    "sprite_vtt_url": "https://cdn.zibnetwork.com/objects/<sprite_vtt_file_id>"
  },
  "aspect_variants": {                         // omitted if tenant didn't opt in; see "Aspect variants" above
    "9:16": {
      "hls_manifest_url": "https://cdn.zibnetwork.com/stream/<vertical_file_id>/master.m3u8",
      "poster_url":       "https://cdn.zibnetwork.com/objects/<vertical_poster_id>"
    }
  },
  "timestamp":           "2026-04-08T17:32:14.000Z"
}

// encoding.progress — NOT EMITTED. Kept here only so that anyone who built
// against this shape can recognise it. No such webhook is delivered; poll
// GET /v1/api/pipeline/{file_id} and read the encoding stage's progress.
//
// You don't need this event to know the job will eventually finish — the
// existing encoding.complete event still fires. encoding.progress is purely
// for UI feedback.
{
  "event":     "encoding.progress",
  "job_id":    "<encoding_jobs.id>",
  "file_id":   "a1b2c3d4-...",
  "progress":  47,                 // integer 0–100
  "stage":     "encoding",         // "encoding" | "sharding"
  "timestamp": "2026-04-08T17:31:08.000Z"
}

// transcription.complete — fires when the SRT/WebVTT artefact has been
// produced and stored. Fetch via https://cdn.zibnetwork.com/objects/<srt_file_id>
{
  "event":        "transcription.complete",
  "job_id":       "<encoding_jobs.id OR compute_jobs.id>",
  "file_id":      "a1b2c3d4-...",
  "srt_file_id":  "f00d...",
  "timestamp":    "2026-04-08T17:34:02.000Z"
}

// vision.complete — fires when the ZibSidecar JSON has been produced and
// stored. Resolve sidecar_file_id via /v1/api/object-url, then fetch that URL
// and parse as JSON for the full sidecar (scenes, IAB categories, etc.).
{
  "event":            "vision.complete",
  "job_id":           "<encoding_jobs.id OR compute_jobs.id>",
  "file_id":          "a1b2c3d4-...",
  "sidecar_file_id":  "ba11...",
  "timestamp":        "2026-04-08T17:36:48.000Z"
}

Verifying signatures

Every webhook request includes an X-ZiB-Signature header containing an HMAC-SHA256 signature of the raw request body. Always verify this before processing the payload.

import crypto from 'crypto';

export async function POST(req) {
  // Read raw body before JSON parsing — signature is over raw bytes
  const body = await req.text();
  const sig = req.headers.get('x-zib-signature'); // "sha256=<hex>"

  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', process.env.ZIB_WEBHOOK_SECRET)
      .update(body)
      .digest('hex');

  if (sig !== expected) {
    return new Response('Unauthorized', { status: 401 });
  }

  const payload = JSON.parse(body);

  if (payload.event === 'file.ready') {
    // update your DB with cdn_url, mark upload complete, etc.
  }

  if (payload.event === 'encoding.complete') {
    // store hls_manifest_url, notify your users, etc.
  }

  return new Response('OK');
}

Deleting Files

When you remove an asset from your application — a creator deletes a piece of content, a poster gets replaced, a blog post comes down — call the delete endpoint to remove the underlying bytes from ZiB. A single call cleans up everything: the encrypted chunks on every node holding them, any encoded HLS segments, the database row, the bucket counters, and the Cloudflare CDN cache.

Two ways to delete

Pick whichever you have on hand. Most tenants store the file_id returned by uploadDirect() alongside their content row, so the by-file_id form is usually the cheaper path.

# Form A — by file_id (preferred)
curl -X DELETE \
  -H "Authorization: Bearer $ZIB_ACCESS_KEY:$ZIB_SECRET_KEY" \
  https://api.zibnetwork.com/v1/api/file/01846192-315c-4f0a-b766-12b18a26b209

# Form B — by bucket + object_key (S3-shaped)
curl -X DELETE \
  -H "Authorization: Bearer $ZIB_ACCESS_KEY:$ZIB_SECRET_KEY" \
  https://api.zibnetwork.com/v1/api/storage/posters/abc123/poster.card.webp

Response shape

{
  "success": true,
  "file_id": "01846192-315c-4f0a-b766-12b18a26b209",
  "bucket": "posters",
  "key": "abc123/poster.card.webp",
  "deleted": {
    "video_segments": 0,
    "encoding_jobs": 0,
    "shards": 12,
    "s3_objects": 1,
    "files": 1
  },
  "node_cleanup": {
    "ok": 12,
    "failed": 0,
    "queued_for_offline": 4
  },
  "encoding_jobs_cancelled": 0
}

The deleted map shows row counts removed from each table — shards is a legacy field name that now counts chunk-holder records, not erasure-coded shards. The node_cleanup map distinguishes nodes that confirmed the delete synchronously (ok) from those that didn't respond in time (failed) — the latter still get a queued pending_deletions row that the node consumes on its next heartbeat, so eventual cleanup is guaranteed even when a node is offline at the moment you call.

Idempotency

Deleting a file_id that doesn't exist (or that belongs to another customer) returns 200 with { success: true, already_deleted: true } rather than 404. This deliberately doesn't leak ownership info, and it makes "clean up everything in this list" loops trivially safe to retry.

// Repeat call after the file is gone
{
  "success": true,
  "already_deleted": true,
  "file_id": "01846192-315c-4f0a-b766-12b18a26b209"
}

Side effects

• In-flight encoding cancelled. If you delete a video while it's still being encoded, the encoding job is marked cancelled before the bytes go away. The encoder won't deliver any further encoding.* webhooks for that file_id.
• CDN cache purged. ZiB calls Cloudflare's purge API for both cdn.zibnetwork.com/objects/{file_id} and cdn.zibnetwork.com/stream/{file_id}/. Worldwide eviction typically completes within ~30 seconds. Until then, edges with a warm cache may continue to serve the asset.
• Source bytes removed and disk reclaimed. Every node holding an encrypted chunk of this file is told to drop it. Holders then reconcile against the live object set, untag the now-orphaned chunks, and garbage-collect them — so the disk is genuinely returned to the network, not merely dereferenced. Reclamation is asynchronous and typically completes within a GC cycle of the delete.
• Bucket + storage counters decremented. Reflected immediately in /v1/api/me/buckets and your storage usage dashboard.

The file.deleted webhook

If you have an account-level webhook URL configured, ZiB fires file.deleted after a successful delete. The shape mirrors file.ready so the same handler can route by event name. Headers: X-ZiB-Event: file.deleted, X-ZiB-File-ID, and the standard X-ZiB-Signature: sha256={hex}.

{
  "event": "file.deleted",
  "file_id": "01846192-315c-4f0a-b766-12b18a26b209",
  "bucket": "posters",
  "key": "abc123/poster.card.webp",
  "timestamp": "2026-05-14T03:21:09.482Z"
}

The webhook is fire-and-forget — the API response returns as soon as the bytes are gone, and webhook delivery happens asynchronously with the same 3-attempt retry + exponential backoff as every other ZiB webhook. Don't treat it as your trigger to remove the row from your DB — the API response already told you the delete succeeded. The webhook is for fan-out (audit logs, search index invalidation, etc.) when multiple systems want to know.

Recommended patterns

Pattern 1 — content row delete cascades to ZiB. When a creator removes a piece of content, fan out to ZiB for every asset stored on the row.

// app/api/content/[id]/delete/route.ts
import { NextResponse } from 'next/server';

export async function DELETE(req: Request, { params }: { params: { id: string } }) {
  const content = await db.content.findUnique({ where: { id: params.id } });
  if (!content) return NextResponse.json({ ok: true }, { status: 200 });

  // 1. Collect every ZiB file_id this row references.
  const fileIds = [
    content.video_file_id,
    content.poster_thumb_id,
    content.poster_card_id,
    content.poster_hero_id,
  ].filter(Boolean);

  // 2. Delete from ZiB in parallel — the endpoint is idempotent so retries are safe.
  await Promise.all(
    fileIds.map((id) =>
      fetch(`https://api.zibnetwork.com/v1/api/file/${id}`, {
        method: 'DELETE',
        headers: { Authorization: `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}` },
      }).catch((e) => console.warn(`ZiB delete failed for ${id}`, e))
    )
  );

  // 3. Delete the local row last — if step 2 partially fails, your DB still
  //    holds the file_ids so a cleanup job can retry.
  await db.content.delete({ where: { id: params.id } });
  return NextResponse.json({ ok: true });
}

Pattern 2 — replace an asset. Uploading a new file to the same (bucket, object_key) as an existing asset automatically evicts the prior bytes from every node and decrements your storage counters — no explicit DELETE call is needed. Just upload the new asset and write the new file_id to your local row.

async function replacePoster(contentId: string, newFile: File) {
  // 1. Upload the new poster to the same object_key. ZiB detects the
  //    existing row at (bucket, object_key), cancels any in-flight
  //    encoding on the prior file_id, fires file.failed for it, and
  //    evicts the prior bytes from every holding node in the background.
  const init = await fetch('/api/posters/upload-initiate', { method: 'POST', body: JSON.stringify({ contentId }) });
  const registration = await init.json();
  const { file_id: newFileId } = await ZiBStorage.uploadDirect(newFile, registration);

  // 2. Write the new file_id to your row. The supersede flow has already
  //    taken care of evicting the prior bytes — no follow-up DELETE needed.
  await db.content.update({ where: { id: contentId }, data: { poster_card_id: newFileId } });
}

Two corollaries:

• If you receive file.failed with cancelled_reason: "superseded by re-upload to same bucket+object_key", it's informational only — you don't need to take any action; the eviction is already underway.
• Explicit DELETE /v1/api/file/{file_id} is still the right call when you want to remove a file without replacing it (Pattern 1 above) — that path additionally drops the audit row + fires file.deleted.

Security Model

Why credentials must stay on the server

The upload/initiate endpoint uses your master credentials, which have full access to your ZiB account — all buckets, all objects, all quota. Exposing these in browser JavaScript would let anyone who reads your source code upload to your buckets and exhaust your storage quota.

The registration object returned by initiate authorises a single upload to a single pre-determined location. It cannot be used to list buckets, delete objects, or create a second object, and the backend refuses a second, different set of bytes for the same id. That bound is what makes it safe to pass from your server to the browser — not an absence of secrets, which is the part integrators most often get wrong.

Self-enforcing encryption

ZiB's encryption model is self-enforcing. If an attacker obtained a registration token and uploaded plaintext bytes directly to the node URL (bypassing the SDK), the CDN would decrypt those bytes using the key generated at initiate time and return garbage — because the bytes stored on the node would not be valid ciphertext for that key.

There is no configuration flag, no "plaintext mode", and no bypass. The CDN always decrypts. Files that were not encrypted correctly before upload cannot be served correctly — ever. This makes the security property durable even if an integration makes a mistake.

Job Status API

Webhooks are the fastest way to know a file finished encoding, but if you need to render progress to an end user (an upload dashboard, a "your video is processing" screen, a retry button), poll GET /v1/api/my-jobs. Every encoding job in your account is returned with its current lifecycle phase — from queued all the way through safe (replicated to enough peers that the file is durable).

Lifecycle phases

Each job is in exactly one phase:

• queued — accepted, waiting for a node to claim it
• encoding — FFmpeg is running; phase_progress_pct ticks 0–100
• sharding — encoded segments are being hashed + written to storage
• local_complete — all bytes on the originating node, awaiting backend greenlight
• replicating — segments are being pulled to peer nodes
• safe — ✅ 3+ peers confirmed; the file is durably stored and will survive any single-node failure. replication_safe_at is set.
• failed — transient failure, auto-retrying (retry_after tells when)
• failed_user_action — retries exhausted; surface a Retry button to the user
• cancelled — user-cancelled; derivatives being cleaned up

List jobs

curl -s https://api.zibnetwork.com/v1/api/my-jobs \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}"

# Filter:
curl -s "https://api.zibnetwork.com/v1/api/my-jobs?status=all" \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}"

?status=active (default) returns jobs whose phase is not safe or cancelled. ?status=all returns everything.

Response

{
  "jobs": [
    {
      "file_id": "0c8e3765-9b2b-4a29-82cb-2f1911fe750c",
      "title": "trailer-final.mp4",
      "phase": "replicating",
      "phase_progress_pct": 66.7,
      "phase_detail": "peer 2 of 3 verified",
      "phase_updated_at": "2026-04-24T05:12:04Z",
      "replication_peer_count": 2,
      "replication_target_count": 3,
      "replication_safe_at": null,
      "retry_count": 0,
      "last_error": null,
      "cancellable": true,
      "retriable": false,
      "created_at": "2026-04-24T04:58:12Z",
      "node_id": "ZB-899233"
    }
  ]
}

Cancel a job

curl -X DELETE https://api.zibnetwork.com/v1/api/my-jobs/${FILE_ID} \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"reason":"user_abandoned_upload"}'

Sets phase=cancelled and queues cleanup commands to every node that holds any segment of the file. Not reversible. Only valid while cancellable: true.

Retry a failed job

curl -X POST https://api.zibnetwork.com/v1/api/my-jobs/${FILE_ID}/retry \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}"

Resets a failed_user_action job back to queued. Use this behind a Retry button in your UI. Only valid while retriable: true.

Suggested polling cadence

• While your UI is visible and you have any job in a non-terminal phase: every 5 s
• Background tab or no active jobs: every 30 s
• Webhooks remain the preferred signal for terminal transitions — use /my-jobs for in-flight progress UX

The durability guarantee

Once a job reaches phase: "safe", the file has ≥3 verified non-originator peers holding every segment. From that point:

• Any one peer can go offline permanently and the file is still served
• The originating node can freely reclaim its local copy
• Playback is served through cdn.zibnetwork.com with automatic failover between peers

Before safe is reached, the originator's bytes are unconditionally protected — the file cannot be lost to a transient failure on the originating node while replication is in progress.

Compute / AI

ZiB Compute is an optional AI inference layer built on top of ZiB storage. Compute-capable nodes run transcription and vision analysis on videos stored in the network. Output is an encrypted WebVTT subtitle file (auto-injected into the HLS manifest) and an encrypted ZibSidecar JSON — a full metadata envelope covering transcription, chapters, scene understanding, IAB content taxonomy, GARM brand safety, clip suggestions, and thumbnail candidates.

Trigger AI from an encoding request

Pass transcription and/or vision options to startEncoding() — the encoding node runs AI immediately after encoding while the decrypted source is already in memory.

const { encoding_id } = await zib.startEncoding(fileId, {
  transcription: 'recommended',  // 'fastest' | 'recommended' | 'accurate'
  vision: 'standard'             // 'standard' | 'hq'
});

// Poll until complete
const status = await zib.getEncodingStatus(encoding_id);
// status.srt_file_id    → WebVTT file (auto-injected into HLS manifest)
// status.sidecar_file_id → ZibSidecar JSON

Standalone compute jobs

Run transcription or vision on any already-stored video — no re-encoding needed.

// Standalone transcription
const { job_id } = await zib.submitTranscription(fileId, 'recommended');

// Standalone vision AI
const { job_id } = await zib.submitVisionAI(fileId, 'standard');

// Poll job status
const result = await zib.getComputeStatus(job_id);
// result.status          → 'queued' | 'processing' | 'complete' | 'failed'
// result.srt_file_id     → WebVTT file ID (when complete)
// result.sidecar_file_id → ZibSidecar file ID (when complete)

Reading the ZibSidecar

The CDN decrypts the sidecar on the fly — fetch the CDN URL directly and parse as JSON.

// Get the sidecar CDN URL from job status
const status = await zib.getComputeStatus(job_id);
const sidecarUrl = zib.getCdnUrl(status.sidecar_file_id);

// Fetch and parse
const sidecar = await fetch(sidecarUrl).then(r => r.json());

// Key fields:
sidecar.scene_understanding.executive_summary        // 150-200 word summary
sidecar.content_classification.garm.brand_safety_score  // 0.0–1.0
sidecar.clip_suggestions[0].virality_score           // 0.0–1.0
sidecar.chapters_youtube_format                      // paste into YouTube description
sidecar.transcript.full_text                         // full transcript string
sidecar.transcript.segments[0].intent               // hook / payoff / cta / ...
sidecar.content_classification.iab_categories[0].name  // IAB 3.0 taxonomy

Quality tiers

Deep-dive docs

Publishers (Distribution)

A publisher is an app or service that displays ZiB-hosted titles to its own audience — distinct from a creator (who uploads content) and a customer(a storage account). Creators' ingest + encode is on ZiB; as a publisher you cover the delivery egress for what your viewers watch, paid from a prepaid USDC balance that decrements in near-real-time.

1 · Onboard

Sign in at app.zibnetwork.com/publisher and submit your details. A ZiB admin reviews and activates the account. Once active, generate your API key from the dashboard (the secret is shown once) and fund your balance.

2 · Read the catalogue (server-side, API key)

Your backend pulls the catalogue of titles available to you. Each entry is tagged live (currently published — may come and go as creators publish/unpublish) or licensed (held for you by an approved avail window — guaranteed present).

curl https://api.zibnetwork.com/v1/api/publisher/catalog \
  -H "Authorization: Bearer $ZIB_PUBLISHER_KEY:$ZIB_PUBLISHER_SECRET"

# → { "count": N, "titles": [ {
#      "id": "<title_id>", "file_id": "<file_id>", "title": "...", "creator": "...",
#      "content_type": "movie", "availability": "live" | "licensed",
#      "thumbnail_horizontal_url": "...", "thumbnail_vertical_url": "...",
#      "window": { "start": "...", "end": "..." } | null,
#      "playback": { "hls_url": "...", "poster_url": "...", "playability_url": "..." }
#    }, ... ] }

Filters: ?content_type=, ?creator=<slug>, ?availability=live|licensed, ?limit=.

3 · Request a licensing window (avails)

For content you need guaranteed for a period (e.g. a featured slate or a voting window), request an avail. The owning creator approves it; once approved and in-window the title is hard-locked into your catalogue — the creator can't pull it until the window ends. You can also do this visually in the dashboard (/publisher/catalog).

4 · Mint a playback session (server-side, balance-gated)

When a viewer hits play, your backend mints a short-lived session. If your balance is empty this returns 402 — no token, no playback (the balance funds the node operators who serve the bytes, so it can't go negative). Pass the returned session_token + the hls_url to the page.

// Your server — the secret key stays here.
const res = await fetch('https://api.zibnetwork.com/v1/api/publisher/playback-session', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ZIB_PUBLISHER_KEY}:${process.env.ZIB_PUBLISHER_SECRET}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ file_id }),   // file_id from the catalogue entry
});
if (res.status === 402) return renderTopUpPrompt();
const { session_token, hls_url, expires_at } = await res.json();
// send session_token + hls_url to the browser

5 · Check geo-playability (per viewer)

Call the open playability endpoint from the viewer's browser (so ZiB sees the viewer's IP) before playing.

const p = await fetch(`https://api.zibnetwork.com/v1/api/content/${titleId}/playability`)
  .then(r => r.json());
if (!p.playable) showUnavailableInRegion(p.userCountry);

6 · Meter egress in the browser (SDK)

Video segments are served direct from ZiB nodes, so the player reports what it fetched. Start the meter with the session token; it decrements your balance in near-real-time and stops playback when you run dry. Main-thread fetches auto-meter; worker-based players (hls.js / bitmovin / shaka) call recordSegment() from their segment-loaded event.

<script src="https://app.zibnetwork.com/sdk/zib-sdk.js"></script>
<script>
  const meter = ZiBStorage.startPublisherMetering({
    sessionToken: "<session_token>",   // from step 4
    fileId: "<file_id>",
    onExhausted: () => player.pause(),  // balance hit zero
  });

  // hls.js — report each loaded fragment for anti-spoof, server-derived billing
  hls.on(Hls.Events.FRAG_LOADED, (_e, d) =>
    meter.recordSegment({ quality: d.frag.level, index: d.frag.sn, bytes: d.stats.total }));

  // on teardown:
  // meter.stop();
</script>

7 · Top up & monitor

Fund your balance with USDC from the dashboard (deposited to the ZiB escrow, same rail as creators). Egress is billed at the standard retrieval_per_gb rate. Your backend can poll GET /v1/api/publisher/balance and GET /v1/api/publisher/usage/live (last-60-min bytes) — both with the API key — to surface balance + near-real-time usage in your own UI.

Object URLs

Posters, sprite sheets, subtitle tracks and source files are served from cdn.zibnetwork.com/objects/{file_id}. These URLs are becoming signed and short-lived, so there is one rule to follow: store the file_id, not the URL.

Resolving a URL

Same Bearer credentials as the rest of the API. Scoped to your own content — a file_id you don't own returns 404.

curl -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  "https://api.zibnetwork.com/v1/api/object-url?file_id=$FILE_ID"

{
  "file_id": "...",
  "url": "https://cdn.zibnetwork.com/objects/...?exp=...&tok=...",
  "expires_in_seconds": 41180        // computed, not a constant — see below
}

Resolving is cheap. Call it when you render rather than caching the URL until it expires.

The URL is stable for an hour, and that is on purpose

expires_in_seconds is the real remaining life, computed per response — not a fixed 12 hours. It is smaller than 43200 for most of any given hour, and here is why that matters. The expiry we sign is quantised to the wall-clock hour, so resolving the same file_id twice inside the same hour returns a byte-identical URL — same exp, same tok. The token is then valid for 12 hours from the top of that hour, so anything you resolve has between 11 and 12 hours of life left.

Resolving many at once

A catalog grid rendering twenty posters should not be twenty round trips. Post up to 100 ids in one call. Ids you do not own — or that do not exist — come back null rather than failing the whole batch, so one bad id does not cost you the other nineteen.

curl -X POST -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"file_ids":["<uuid-a>","<uuid-b>"]}' \
  "https://api.zibnetwork.com/v1/api/object-urls"

{ "urls": { "<uuid-a>": "https://cdn.zibnetwork.com/objects/...?exp=...&tok=...",
            "<uuid-b>": null },
  "expires_in_seconds": 41180 }

Rate limits: none are applied today. That is a statement of fact rather than a guarantee — if your volume is high enough that a limit would hurt, tell us the number before you build against the absence of one.

References inside a signed document

A sprite VTT is a document whose cues are object URLs, pointing at the sprite sheets. Those are signed for you when the VTT is served — absolute URLs, minted per response, with the same lifetime as any other, and that response is cached for an hour so it can never outlive its own tokens. You do not need to resolve them yourself.

Server-side retrieval

This endpoint is plain HTTP with Bearer credentials, so it is callable from an ad server, a backend job, or a server-rendered route — anywhere you can make a request. It is the supported server-side path, and it is the answer to “how do I get a URL without a browser”: the SDK's fetchObject() decrypts client-side and cannot help you here, but nothing about resolving a URL requires the SDK.

What is not affected

HLS playback is unchanged — manifests, segments and keys are already signed, and players never touch this path. Uploads, credentials and webhook payloads are unchanged. If you only stream video, or you already resolve URLs at render time, there is nothing to do.

Testing before enforcement

Enforcement is currently off. It was enabled briefly on 2026-08-19 and switched back off within the hour: bare object URLs turned out to be embedded in live integrations built against the previous guidance on this page, which is our error, not theirs. It will not be enabled again without coordinating with every integration first.

A presented token is always judged, whether or not enforcement is on — only an absent one gets the lenient path. So a deliberately bad token gives you the real behaviour today:

# The &cb= is not decoration — see the warning below.
curl -i "https://cdn.zibnetwork.com/objects/$FILE_ID?exp=1&tok=bad&cb=$RANDOM"   # 403
curl -i "https://cdn.zibnetwork.com/objects/$FILE_ID?cb=$RANDOM"                 # 200 — absent token is lenient

The same effect is worth planning for at switch-on: a URL that was cached while unsigned keeps serving from the edge for up to 24 hours afterwards, so enforcement will look partially applied for a day. Check cf-cache-status and age before concluding anything from a 200.

Rehearsing the real switch

A bad token proves the gate works; it does not prove your code has stopped sending bare URLs. For that we can enable enforcement across your content only, leaving every other tenant untouched, so you can verify in your own staging or production before the global switch. Ask us and we will add your customer id to the opt-in list — and remove it the moment you say so.

Streaming URLs are not affected

/stream/{file_id}/master.m3u8 and manifest.mpd are safe to store and are not moving behind a token. The distinction is worth understanding, because it is the rule rather than an exception: a manifest is generated fresh on every request, so the signed URIs inside it — the AES key, the subtitle playlist — are minted at fetch time and are never stale. An object URL, by contrast, carries its own credential, which is why storing one goes bad. Store a URL that is resolved when it is fetched; do not store a URL that already contains a token. (Storing a manifest's body would break for the same reason as an object URL.)

Errors & Troubleshooting

Real status codes you'll see, what they mean, and what (if anything) to do about them. Every ZiB error response is JSON with an error field describing the cause.

HTTP status reference

Tenant-proxy 502s — the relay trap

If your tenant has a Next.js / Express / Lambda proxy in front of ZiB (typical for browser clients that don't hold master credentials), be aware: that proxy almost certainly translates any non-JSON ZiB response into a generic 502. The browser then shows "Failed to initiate upload (502)" or similar.

The 502 is rarely the actual bug. It's a relay. The real cause is in the proxy's server-side log:

• If the proxy logs ZiB returned 503 — fleet capacity, see 503 above.
• If ZiB returned 401 — master credentials wrong on the proxy.
• If ZiB returned 5xx HTML — temporary backend issue, retry.
• If connection refused / timeout — proxy can't reach ZiB; check egress firewall.

Surface the upstream status code in your proxy's 502 response body. Future-you debugging at 3am will thank you.

Common silent failures

These don't throw an error, but produce wrong behaviour. All have bitten real tenants:

• Missing webhook_url in the request body. If you use per-request webhook config but forget to include the URL on a particular call, ZiB stores null, no events fire, and there's no error. Verify with SELECT webhook_url FROM encoding_jobs WHERE id = '...' if you have DB access, or check your request-builder for conditional logic that drops the field.
• Polling that never stops on terminal phase. If your code treats any non-error response as "keep polling", you'll hammer the endpoint forever after the encode is done. Always break on phase === 'safe' / 'failed_user_action' / 'cancelled'. See Video Encoding section.
• Routing logic that keys on encoding_id. Re-encode requests can return a different encoding_id if forced or after supersede. Always route by file_id in your storage and references; treat encoding_id as job-ephemeral.
• Reading status when you should read phase. Both fields are present in responses; they mostly agree but phase is canonical. Code keyed on status may miss new phase values added in the future.
• Webhook handler that 200s before persisting. ZiB retries on non-2xx but stops on 200. If your handler returns 200 then crashes before writing the event to your DB, you've dropped it. Persist first, ack second.

Getting help

When opening a support thread, include:

• customer_id and the specific file_id / encoding_id involved.
• UTC timestamp of the failing request (within ±30 s is plenty).
• The full request body (redact sensitive fields like webhook_secret) and the response status + body.
• If a proxy is involved, the upstream response your proxy received from ZiB — not just the 502 your code saw.