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

using OleqFiles;

var oleqFiles = new OleqFilesClient();

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
`HttpClient`	no	Inject a shared `HttpClient`

*Required unless OLEQFILES_API_KEY is set.

Apps

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

List apps

var list = await oleqFiles.Apps.ListAsync(new PaginationQuery { Page = 1, PageSize = 20 });

Get an app

var app = await oleqFiles.Apps.GetAsync(appId);

Create an app

var app = await oleqFiles.Apps.CreateAsync(new CreateAppInput
{
    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.UpdateAsync(appId, new UpdateAppInput
{
    Name = "Marketing",
    Slug = "marketing-v2",
});

Archive an app

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

await oleqFiles.Apps.DeleteAsync(appId);

Promote sandbox → production

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

var promoted = await oleqFiles.Apps.PromoteAsync(appId);

Files

All file operations go through oleqFiles.Files. Prefer Files.UploadAsync() for the full upload flow.

Upload a file

await using var stream = File.OpenRead("hero.png");

var result = await oleqFiles.Files.UploadAsync(new UploadFileInput
{
    AppId = app.Id,
    Name = "hero.png",
    MimeType = "image/png",
    Data = stream,
});

Console.WriteLine(result.Id);  // S3 object key — store this in your DB
Console.WriteLine(result.Src); // public CDN URL

Upload from an HTML form

Browser form with a plain file input — post to your backend (never expose the API key in the browser):

wwwroot/upload.html

<form action="/upload" method="post" enctype="multipart/form-data">
  <input type="file" name="file" accept="image/*" required />
  <button type="submit">Upload</button>
</form>

UploadController.cs

[HttpPost("upload")]
public async Task<IActionResult> Upload(IFormFile file, CancellationToken ct)
{
    if (file is null || file.Length == 0)
        return BadRequest(new { error = "file is required" });

    try
    {
        await using var stream = file.OpenReadStream();
        var result = await _oleqFiles.Files.UploadAsync(new UploadFileInput
        {
            AppId = _options.AppId,
            Name = file.FileName,
            MimeType = file.ContentType ?? "application/octet-stream",
            Data = stream,
        }, ct);

        return Ok(new { id = result.Id, src = result.Src });
    }
    catch (OleqFilesException ex)
    {
        return StatusCode(ex.StatusCode, new { error = ex.Message });
    }
}

List files

var files = await oleqFiles.Files.ListAsync(new ListUploadsQuery
{
    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:

var usage = await oleqFiles.Usage.GetAsync();
// usage.StorageOverLimit, usage.HiddenFileCount, usage.LimitBytes, …

Get file metadata

var record = await oleqFiles.Files.GetAsync(id);

Get public URL

var urlResponse = await oleqFiles.Files.GetUrlAsync(id);

Delete a file

await oleqFiles.Files.DeleteAsync(id);

Errors

API and upload failures throw OleqFilesException:

try
{
    await oleqFiles.Files.GetAsync(id);
}
catch (OleqFilesException ex)
{
    Console.Error.WriteLine($"{ex.StatusCode}: {ex.Message}");
    // ex.Body is the raw response text when available
}

Construction throws ArgumentException when:

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

Usage

On this page