File Manager API — Integration Guide

This guide is everything a 3rd-party application needs to integrate with the File Manager API: a REST API for buckets, folders, files, shareable download links, a private file manager, and a real-time event feed. Every call is authenticated with a vendor API key and is automatically scoped to your tenant.

1. Authentication

Authenticate every request with a vendor API key (it looks like `fmsk_…`). Create one in your vendor dashboard under “API keys” — the secret is shown only once, so store it safely. Send it on every request as a Bearer token (or the `x-api-key` header). Each key carries a set of scopes (permissions) and may optionally be restricted to specific buckets; a request that needs a scope the key doesn’t have is rejected with `403`. The SAME key authenticates all three transports — the REST endpoints, the SSE feed (`/events`), and the WebSocket feed (`/ws`) — so one credential drives everything.

# Either header works:
-H "Authorization: Bearer fmsk_YOUR_KEY"
-H "x-api-key: fmsk_YOUR_KEY"

Every endpoint declares the scope it requires. Grant a key only the scopes it needs. The available scopes:

2. Quick start

curl -H "Authorization: Bearer fmsk_YOUR_KEY" \
  https://cdn.betazeninfotech.com/api/v1/buckets

curl -X POST https://cdn.betazeninfotech.com/api/v1/buckets \
  -H "Authorization: Bearer fmsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"invoices"}'

curl -X POST https://cdn.betazeninfotech.com/api/v1/buckets/BUCKET_ID/files \
  -H "Authorization: Bearer fmsk_YOUR_KEY" \
  -F "file=@/path/to/file.pdf" -F "path=/"

curl -X POST https://cdn.betazeninfotech.com/api/v1/files/FILE_ID/links \
  -H "Authorization: Bearer fmsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"public"}'

curl -N https://cdn.betazeninfotech.com/api/v1/events \
  -H "Authorization: Bearer fmsk_YOUR_KEY" \
  -H "Accept: text/event-stream"

3. Core concepts

Buckets

Top-level containers for your files (one tenant can have many). Names are unique per vendor. Creating a bucket also provisions a matching folder in your File Manager.

Folders

Optional hierarchy inside a bucket. Files can live at the bucket root or inside nested folders.

Files

Uploaded objects. Small files use a single multipart/form-data upload; large files use the multipart flow (init → upload parts → complete). Uploads are also mirrored into your File Manager so they show up there.

Share links

Three kinds of shareable download URLs: public (/p/…, anyone with the URL), temporary (/t/…, auto-expires), and private (/d/…, requires a 3rd-party JWT). Temporary links require an explicit expiresIn; public/private links can be made permanent with neverExpire. Links stream the file through the app, so they work from any browser.

File Manager

A private, jailed filesystem per tenant. You can create folders, read/write text files, upload, compress/extract, change permissions, hide files, and move items to a recoverable Trash (restore or permanently delete).

Real-time events

A live feed of everything happening on your account (uploads, deletes, link creation, file-manager operations…), delivered over a standard HTTPS stream (Server-Sent Events). Use it to keep a 3rd-party UI in sync instantly instead of polling.

4. API reference

Every endpoint with its required scope. For full request/response details and a live tester, open the interactive explorer.

5. Real-time events (Server-Sent Events)

Open `GET /events` with a streaming HTTP client and your API key; the server keeps the connection open and pushes one event per change as it happens. Each event is a small JSON object. The connection auto-recovers: on reconnect, send the `Last-Event-ID` header (the id of the last event you saw) and you’ll receive everything you missed. For a one-shot catch-up (e.g. on first load) call `GET /events?since=<cursor>` for a JSON list plus a cursor to continue from. Keys restricted to specific buckets only receive events for those buckets.

{
  "id": "6a2e7012c12f65f87232a1f3",
  "type": "file.upload",
  "vendorId": "6a2d7e0a626116c181d92a71",
  "resourceType": "file",
  "resourceId": "6a2e70b4c12f65f87232a201",
  "bucketId": "6a2e6fc6c12f65f87232a172",
  "actorType": "apikey",
  "at": "2026-06-14T09:10:42.615Z"
}

const BASE = 'https://cdn.betazeninfotech.com/api/v1';
const KEY = process.env.FM_API_KEY; // fmsk_...

// 1) Fast initial load + resume cursor
let cursor = null;
async function catchUp() {
  const url = new URL(BASE + '/events');
  if (cursor) url.searchParams.set('since', cursor);
  const r = await fetch(url, { headers: { Authorization: 'Bearer ' + KEY } });
  const { events, cursor: next } = await r.json();
  events.forEach(handle);
  if (next) cursor = next;
}

// 2) Live stream (auto-reconnect with Last-Event-ID)
async function stream() {
  const res = await fetch(BASE + '/events', {
    headers: { Authorization: 'Bearer ' + KEY, Accept: 'text/event-stream',
               ...(cursor ? { 'Last-Event-ID': cursor } : {}) }
  });
  const reader = res.body.getReader();
  const dec = new TextDecoder();
  let buf = '';
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buf += dec.decode(value, { stream: true });
    let i;
    while ((i = buf.indexOf('\n\n')) >= 0) {
      const frame = buf.slice(0, i); buf = buf.slice(i + 2);
      const line = frame.split('\n').find((l) => l.startsWith('data: '));
      if (line) { const e = JSON.parse(line.slice(6)); cursor = e.id; handle(e); }
    }
  }
  setTimeout(stream, 1000); // reconnect on drop
}

function handle(e) { console.log(e.type, e.resourceId, e.at); }
await catchUp();
stream();

import WebSocket from 'ws';
const ws = new WebSocket('wss://cdn.betazeninfotech.com/api/v1/ws', {
  headers: { Authorization: 'Bearer fmsk_YOUR_KEY' }   // or x-api-key
});
ws.on('open', () => console.log('connected'));
ws.on('message', (data) => {
  const e = JSON.parse(data.toString());
  if (e.type === '__connected') return;                // hello + resume cursor
  console.log(e.type, e.resourceId, e.at);
});
ws.on('close', () => setTimeout(reconnect, 1000));     // reconnect with ?since=<lastId>

const ws = new WebSocket('wss://cdn.betazeninfotech.com/api/v1/ws?api_key=fmsk_YOUR_KEY');
ws.onmessage = (m) => { const e = JSON.parse(m.data); console.log(e.type); };

wscat -c "wss://cdn.betazeninfotech.com/api/v1/ws" -H "Authorization: Bearer fmsk_YOUR_KEY"

6. Responses & errors

A successful response returns the requested JSON directly (HTTP 200, or 201 on create). An error returns `{ "error": { "code": "…", "message": "…" } }` with an appropriate HTTP status:

{ "error": { "code": "FORBIDDEN", "message": "missing events:subscribe scope" } }

7. Tools & downloads