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)

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

dotnet add package Zeridion.Flare

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

TypeScript / JS

npm install @zeridion/flare

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

Python

pip install zeridion-flare

Requires Python 3.10+. The Python SDK is in Beta — a feature-complete synchronous REST client. See the Python SDK reference for the full API surface.

Go

go get github.com/zeridion/flare-go

Requires Go 1.22+. Zero third-party dependencies (standard library only). See the Go SDK reference.

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")

Requires Java 17+. See the Java SDK reference.

PHP

composer require zeridion/flare

Requires PHP 8.2+ with ext-curl and ext-json. Zero third-party dependencies. See the PHP SDK reference.

Ruby

gem install zeridion-flare

Requires Ruby 3.2+. Zero runtime dependencies. See the Ruby SDK reference.

curl

No installation needed — use your API key directly with any HTTP client.

2. Configure your API key

.NET

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).

TypeScript / JS

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!,
});

Python

import os
from zeridion_flare import FlareClient

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

Go

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

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

Java

import com.zeridion.flare.FlareClient;

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

PHP

use Zeridion\Flare\FlareClient;

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

Ruby

require "zeridion_flare"

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

curl

Set the key as a shell variable for reuse:

export FLARE_API_KEY="zf_live_sk_xxxxxxxxxxxxxxxxxxxx"

3. Enqueue your first job

.NET

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.

TypeScript / JS

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));
}

Python

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"

Go

package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    client, err := flare.NewClient() // reads FLARE_API_KEY
    if err != nil {
        log.Fatal(err)
    }

    job, err := client.CreateJob(context.Background(), &flare.CreateJobRequest{
        JobType: "SendWelcomeEmail",
        Payload: map[string]any{"email": "alice@example.com", "name": "Alice"},
        Queue:   "default",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(job.ID, job.State) // "job_abc123 pending"
}

Java

import com.zeridion.flare.FlareClient;
import java.util.Map;

FlareClient client = FlareClient.builder().build(); // reads FLARE_API_KEY

Map<String, Object> job = client.createJob(Map.of(
    "job_type", "SendWelcomeEmail",
    "payload", Map.of("email", "alice@example.com", "name", "Alice"),
    "queue", "default",
    "max_attempts", 3
));

System.out.println(job.get("id") + " " + job.get("state")); // "job_abc123 pending"

PHP

use Zeridion\Flare\FlareClient;

$client = new FlareClient(); // reads FLARE_API_KEY

$job = $client->createJob([
    'job_type' => 'SendWelcomeEmail',
    'payload'  => ['email' => 'alice@example.com', 'name' => 'Alice'],
    'queue'    => 'default',
    'max_attempts' => 3,
]);

echo $job['id'], ' ', $job['state']; // "job_abc123 pending"

Ruby

require "zeridion_flare"

client = Zeridion::Flare::Client.new # reads FLARE_API_KEY

job = client.create_job(
  "job_type" => "SendWelcomeEmail",
  "payload"  => { "email" => "alice@example.com", "name" => "Alice" },
  "queue"    => "default",
  "max_attempts" => 3,
)

puts job["id"], job["state"] # "job_abc123", "pending"

curl

$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 seven 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

See also

• Jobs API — full job-create, status, cancel, and export reference
• IJob<T> — the .NET interface every job class implements
• Error Handling guide — retry, fallback, and dead-letter patterns