Installation

Zeridion Flare ships an official SDK for seven languages, plus a plain REST API you can call from anything else. Pick your language below — the choice follows you across every tabbed page in these docs.

If you just want to see a job run, start with the Quick Start instead; this page is the deeper reference for install options, runtime support, and verifying a working setup.

Install the package

.NET

dotnet add package Zeridion.Flare

Package Manager Console:

Install-Package Zeridion.Flare

PackageReference:

<PackageReference Include="Zeridion.Flare" Version="0.2.3" />

tip

Replace 0.2.3 with the latest version from NuGet.

TypeScript / JS

npm install @zeridion/flare

pnpm: pnpm add @zeridion/flare · Yarn: yarn add @zeridion/flare · Bun: bun add @zeridion/flare

Python

pip install zeridion-flare

httpx is pulled in automatically as a dependency.

Go

go get github.com/zeridion/flare-go

Java

Maven:

<dependency>
    <groupId>com.zeridion</groupId>
    <artifactId>flare</artifactId>
    <version>0.2.1</version>
</dependency>

Gradle (Kotlin DSL):

implementation("com.zeridion:flare:0.2.1")

PHP

composer require zeridion/flare

Ruby

gem install zeridion-flare

Bundler: add gem "zeridion-flare" to your Gemfile, then bundle install.

curl

Nothing to install — every SDK is a client for the same REST API. See the REST API reference for the raw endpoints.

Runtime compatibility

.NET

The package multi-targets net10.0 and netstandard2.1, so it works across all modern .NET versions without conditional compilation on your side.

Target Framework	Supported .NET Versions	Notes
net10.0	.NET 10	Full feature support, recommended
netstandard2.1	.NET 6, 7, 8, 9	Full feature support

TypeScript / JS

Node 20+, Bun, Deno, Cloudflare Workers, Vercel Edge, Fastly Compute@Edge, or any environment with native fetch and crypto.subtle (or node:crypto in Node). No runtime dependencies.

Python

Python 3.10+ · httpx>=0.27 (installed for you).

The SDK is fully typed with Python 3.10+ union syntax (str | None), so mypy and pyright check your calls without extra stubs.

Go

Go 1.22+. Zero third-party dependencies — standard library only.

Java

Java 17+ (LTS).

PHP

PHP 8.2+ with ext-curl and ext-json. Zero third-party dependencies.

Ruby

Ruby 3.2+. Zero runtime dependencies.

curl

Any HTTP client that can send a bearer token and a JSON body.

Where it runs

.NET

Zeridion Flare works in any .NET project that uses Microsoft.Extensions.Hosting:

• ASP.NET Core Web API / Minimal API — most common
• ASP.NET Core MVC / Razor Pages
• Worker Services (Host.CreateDefaultBuilder)
• Console apps (with HostBuilder)
• Blazor Server

note

Blazor WebAssembly is not supported because jobs execute server-side and require the hosting infrastructure.

TypeScript / JS

Any server-side JavaScript runtime — an Express/Fastify/Nest service, a Next.js route handler, a Worker, or a standalone script.

warning

The client authenticates with a secret key (zf_live_sk_…). Keep it server-side — never ship it in a browser bundle.

Python

Any Python service that can hold a secret key — Django, FastAPI, Flask, or a plain script.

The client is synchronous. To execute jobs as well as enqueue them, the SDK ships a threaded worker host — see the Python SDK reference.

Go

Any Go module — an HTTP service, a CLI, or a long-running worker binary. The SDK includes worker registration and heartbeat calls for building your own execution loop; see the Go SDK reference.

Java

Any JVM application — Spring Boot, Quarkus, Micronaut, or plain Java. A background worker host is included; see the Java SDK reference.

PHP

Any PHP application — Laravel, Symfony, or plain PHP-FPM — plus a CLI worker for executing jobs. See the PHP SDK reference.

Ruby

Any Ruby application — Rails, Sinatra, or a plain script. See the Ruby SDK reference.

curl

Anywhere you can make an HTTPS request — CI steps, shell scripts, or a language without an official SDK yet.

Configuration

Your API key starts with zf_live_sk_ (production) or zf_test_sk_ (test). Every SDK reads FLARE_API_KEY from the environment when you do not pass a key explicitly.

.NET

Add your API key to appsettings.json:

{
  "Zeridion": {
    "ApiKey": "zf_live_sk_xxxxxxxxxxxxxxxxxxxx"
  }
}

Then bind it in Program.cs:

builder.Services.AddZeridionFlare(options =>
{
    options.ApiKey = builder.Configuration["Zeridion:ApiKey"]!;
});

Local development

For local development against the Flare API running in Docker, override ApiBaseUrl in appsettings.Development.json:

{
  "Zeridion": {
    "ApiKey": "zf_test_sk_local_development_key",
    "ApiBaseUrl": "http://localhost:5100"
  }
}

TypeScript / JS

import { FlareClient } from "@zeridion/flare";

const flare = new FlareClient({
  apiKey: process.env.FLARE_API_KEY!,
  // baseUrl: "http://localhost:5100",  // override for local dev
});

baseUrl defaults to https://api.zeridion.com. See FlareClient for retry, timeout, and response-size options.

Python

import os
from zeridion_flare import FlareClient

flare = FlareClient(api_key=os.environ["FLARE_API_KEY"])

Base URL differs from the other SDKs

base_url defaults to https://api.zeridion.com/flare/v1 — the version path is included. An override must include it too:

flare = FlareClient(api_key="...", base_url="http://localhost:5100/flare/v1")

Go

import flare "github.com/zeridion/flare-go"

// Reads FLARE_API_KEY from the environment.
client, err := flare.NewClient()

// Or pass it explicitly, with an optional base-URL override:
client, err = flare.NewClient(
    flare.WithAPIKey("zf_live_sk_..."),
    flare.WithBaseURL("http://localhost:5100"),
)

Java

import com.zeridion.flare.FlareClient;

// Reads FLARE_API_KEY from the environment.
FlareClient client = FlareClient.builder().build();

// Or pass it explicitly, with an optional base-URL override:
FlareClient local = FlareClient.builder()
    .apiKey("zf_live_sk_...")
    .baseUrl("http://localhost:5100")
    .build();

PHP

use Zeridion\Flare\FlareClient;

// Reads FLARE_API_KEY from the environment.
$client = new FlareClient();

// Or pass it explicitly, with an optional base-URL override:
$client = new FlareClient(
    apiKey: 'zf_live_sk_...',
    baseUrl: 'http://localhost:5100',
);

Ruby

require "zeridion_flare"

# Reads FLARE_API_KEY from the environment.
client = Zeridion::Flare::Client.new

# Or pass it explicitly, with an optional base-URL override:
client = Zeridion::Flare::Client.new(
  api_key: "zf_live_sk_...",
  base_url: "http://localhost:5100",
)

curl

Export the key once and reuse it:

export FLARE_API_KEY="zf_live_sk_xxxxxxxxxxxxxxxxxxxx"

Verify installation

Listing jobs is read-only and safe to run against a live project — an empty list still proves the package resolved and the key is valid.

.NET

Run your application and look for the Flare worker startup log in the console output:

dotnet run

You should see log output indicating the worker has started and is polling for jobs. To check the connection directly, resolve IJobClient and list jobs:

var page = await jobs.ListAsync(new ListJobsOptions { Limit = 1 });
Console.WriteLine($"Connected — {page.Items.Count} job(s) returned.");

danger

If ApiKey is missing or empty, the app throws an ArgumentException at startup. This is by design — configuration errors are caught before your app accepts traffic.

TypeScript / JS

await flare.listJobs({ limit: 1 });
console.log("Zeridion Flare is installed and the API key works.");

Python

flare.list_jobs(limit=1)
print("Zeridion Flare is installed and the API key works.")

Go

if _, err := client.ListJobs(ctx, &flare.ListJobsOptions{Limit: 1}); err != nil {
    log.Fatal(err)
}
log.Println("Zeridion Flare is installed and the API key works.")

Java

var filters = new FlareClient.ListJobsOptions();
filters.limit = 1;

client.listJobs(filters);
System.out.println("Zeridion Flare is installed and the API key works.");

PHP

$client->listJobs(limit: 1);
echo "Zeridion Flare is installed and the API key works.\n";

Ruby

client.list_jobs(limit: 1)
puts "Zeridion Flare is installed and the API key works."

curl

curl -s "https://api.zeridion.com/flare/v1/jobs?limit=1" \
  -H "Authorization: Bearer $FLARE_API_KEY"

A 200 with a JSON body means the key is valid. A 401 means the key is wrong or revoked — see Errors.

An authentication failure surfaces as a typed error in every SDK (AuthError or its language equivalent). See Error handling for the full hierarchy.

---

Next → Configuration · Quick Start

See also

• Configuration — DI registration, JobOptions, and runtime tweaks
• Quick Start — enqueue your first job in under five minutes
• SDK overview — pick the SDK for your language