Usage

Portal

Every operation below — apps CRUD, file uploads, listing, deletion — is also available in the portal. The SDK is for automating the same work from your backend.

For raw REST paths, headers, and the low-level presign flow, see HTTP API.

Initialize

import OleqFiles from '@oleq-ai/file-manager';

const oleqfiles = new OleqFiles();

Requires OLEQFILES_API_KEY. See Installation.

Option	Required	Description
`apiKey`	no*	`sk_test_…` or `sk_live_…`
`baseUrl`	no	API origin; defaults to `https://uploadspi.oleq.app`
`organizationId`	no	Sent as `x-organization-id` if set
`fetch`	no	Custom `fetch` (tests, agents)

*Required unless OLEQFILES_API_KEY is set.

Apps

Apps are containers for files. Create them in the portal or with oleqfiles.apps.

List apps

const { apps, meta } = await oleqfiles.apps.list({ page: 1, pageSize: 20 });

Get an app

const app = await oleqfiles.apps.get(appId);

Create an app

const app = await oleqfiles.apps.create({
  name: 'Marketing site',
  slug: 'marketing',
  environment: 'sandbox', // default; or 'production'
});

Sandbox apps pair with sk_test_… keys. Production apps pair with sk_live_….

Update an app

await oleqfiles.apps.update(appId, { name: 'Marketing', slug: 'marketing-v2' });

Archive an app

Soft-deletes the app (files remain until deleted separately):

await oleqfiles.apps.delete(appId);

Promote sandbox → production

One-way promotion when you are ready to go live:

const promoted = await oleqfiles.apps.promote(appId);

Files

All file operations go through oleqfiles.files. Prefer files.upload() for the full upload flow.

Upload a file

import { readFile } from 'node:fs/promises';

const { id, src, file } = await oleqfiles.files.upload({
  appId: app.id,
  name: 'hero.png',
  mimeType: 'image/png',
  data: await readFile('./hero.png'), // Blob | ArrayBuffer | Uint8Array
});

console.log(id); // S3 object key — store this in your DB
console.log(src); // public CDN URL

Browser / framework recipes (HTML, Next.js, NestJS): Examples.

List files

const { files, meta } = await oleqfiles.files.list({
  appId: app.id,
  page: 1,
  pageSize: 50,
  orderBy: 'createdAt:desc',
});

Get usage

Storage limits and hidden-file counts live on the usage endpoint, not the file list:

const usage = await oleqfiles.usage.get();
// usage.storageOverLimit, usage.hiddenFileCount, usage.limitBytes, …

Get file metadata

const record = await oleqfiles.files.get(id);

Get public URL

const { url } = await oleqfiles.files.getUrl(id);

Delete a file

await oleqfiles.files.delete(id);

Errors

API and upload failures throw OleqFilesError:

import OleqFiles, { OleqFilesError } from '@oleq-ai/file-manager';

const oleqfiles = new OleqFiles();

try {
  await oleqfiles.files.get(id);
} catch (err) {
  if (err instanceof OleqFilesError) {
    console.error(err.status, err.message, err.body);
    return;
  }
  throw err;
}

Construction also throws a plain Error when:

OLEQFILES_API_KEY / apiKey is missing
the key does not start with sk_test_… or sk_live_…

Usage

On this page