Quick Start

Run your first job in 5 minutes.

Before you start (~2 min): sign up, create a project, copy your API key. The rest of this guide walks you through enqueueing your first background job with Zeridion Flare.

Prerequisites

A Zeridion Flare API key — create your free project in the dashboard (takes 10 seconds, no credit card)

:::tip Don't have an API key yet? Sign up via the dashboard to create a free account. Your API key will be available in the dashboard immediately — no credit card required. :::

1. Install the SDK

.NET
TypeScript / JS
Python
curl

dotnet add package Zeridion.Flare --prerelease

Targets net10.0 and netstandard2.1 — works on .NET 6 through .NET 10.

npm install @zeridion/flare

Requires Node 20+ or a modern browser (native fetch — no runtime dependencies).

pip install zeridion-flare

Requires Python 3.10+. The Python SDK is currently in early access — join the waitlist to get notified when it reaches GA.

2. Configure your API key

.NET
TypeScript / JS
Python
curl

Add your key to appsettings.json:

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

Your API key starts with zf_live_sk_ (production) or zf_test_sk_ (test).

Pass the key when constructing the client, or read it from an environment variable:

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

const flare = new FlareClient({
  apiKey: process.env.FLARE_API_KEY!,
});

import os
from zeridion_flare import FlareClient

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

Set the key as a shell variable for reuse:

export FLARE_API_KEY="zf_live_sk_xxxxxxxxxxxxxxxxxxxx"

3. Enqueue your first job

.NET
TypeScript / JS
Python
curl

Register in Program.cs:

using Zeridion.Flare;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();
app.UseZeridionFlare();
app.Run();

Define a job:

// IEmailService is your dependency — register it in DI before adding the job.
public sealed class SendWelcomeEmail(IEmailService email) : IJob<NewUserEvent>
{
    public async Task ExecuteAsync(NewUserEvent payload, JobContext ctx)
    {
        await email.SendAsync(payload.Email, "Welcome!", ctx.CancellationToken);
        ctx.Logger.LogInformation("Welcome email sent to {Email}", payload.Email);
    }
}

public sealed record NewUserEvent
{
    public required string Email { get; init; }
    public required string Name { get; init; }
}

Enqueue it:

app.MapPost("/register", async (RegisterRequest req, IJobClient jobs) =>
{
    var user = await CreateUser(req);

    await jobs.EnqueueAsync<SendWelcomeEmail>(
        new NewUserEvent { Email = user.Email, Name = user.Name });

    return Results.Ok(user);
});

AddZeridionFlare scans your assemblies for job classes, registers the HTTP client, job client, and background worker. UseZeridionFlare validates the job-type catalog at startup.

The TypeScript SDK is a thin REST wrapper — you enqueue jobs by type name, and your own worker process polls and executes them.

Enqueue a job:

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

const flare = new FlareClient({ apiKey: process.env.FLARE_API_KEY! });

const job = await flare.createJob({
  job_type: "SendWelcomeEmail",
  payload: { email: "alice@example.com", name: "Alice" },
  queue: "default",
  max_attempts: 3,
});

console.log(job.id, job.state); // "job_abc123", "pending"

Poll and execute (worker loop):

while (true) {
  const { jobs } = await flare.pollWorker({
    worker_id: "worker-1",
    queues: ["default"],
    capacity: 5,
  });

  for (const job of jobs) {
    try {
      // `dispatch` is your application's job router — typically a switch on
      // job.job_type that loads the payload and calls the right handler.
      // See the starter sample for a complete dispatch() implementation.
      await dispatch(job);
      await flare.ackWorker({ job_id: job.id, worker_id: "worker-1", status: "succeeded", duration_ms: 120 });
    } catch (err) {
      await flare.ackWorker({ job_id: job.id, worker_id: "worker-1", status: "failed",
        error: { message: String(err) } });
    }
  }

  await new Promise(r => setTimeout(r, 1000));
}

from zeridion_flare import FlareClient

flare = FlareClient(api_key="zf_live_sk_...")

# Enqueue a job
job = flare.create_job({
    "job_type": "SendWelcomeEmail",
    "payload": {"email": "alice@example.com", "name": "Alice"},
    "queue": "default",
    "max_attempts": 3,
})

print(job["id"], job["state"])  # "job_abc123", "pending"

$FLARE_API_KEY is the shell env var you set in step 2.

curl -X POST https://api.zeridion.com/flare/v1/jobs \
  -H "Authorization: Bearer $FLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_type": "SendWelcomeEmail",
    "payload": { "email": "alice@example.com", "name": "Alice" },
    "queue": "default",
    "max_attempts": 3
  }'

Try in Postman, Insomnia, or any OpenAPI tool

Postman: Download the Zeridion Flare Postman collection and import it. Set the baseUrl and apiKey collection variables once, then run the pre-built requests in order — the Create Job request auto-stores the returned job ID for subsequent Get / Retry / Cancel calls.

Any OpenAPI 3.x tool (Insomnia, Thunder Client, Hoppscotch, Bruno, RapidAPI, …): import the live OpenAPI spec from https://docs.zeridion.com/api/openapi.json. The spec is the canonical machine-readable contract — every endpoint, parameter, response shape, and error code is in there. It updates with every release.

Next steps

SDK overview — feature parity matrix for all three SDKs
Installation details — framework compatibility, project types, and local dev setup
Configuration — customize queues, retries, timeouts, and concurrency
Schedule a job — ScheduleAsync with a delay or specific time (.NET)
Retry strategies — configure [JobConfig(MaxAttempts = 5)] and backoff behavior
Recurring jobs — cron-based IRecurringJob for scheduled tasks
Job continuations — chain dependent jobs
Full .NET SDK Reference — every interface, attribute, and option
TypeScript SDK Reference — FlareClient methods and types
TypeScript starter app — runnable Node.js example: create a job, poll for completion, worker poll + ack

Prerequisites​

1. Install the SDK​

2. Configure your API key​

3. Enqueue your first job​

Try in Postman, Insomnia, or any OpenAPI tool​

Next steps​

See also​