Skip to main content

Glossary

Canonical names, definitions, and per-SDK parameter spellings for the concepts that show up across the API reference, the .NET SDK, and the multi-language SDKs.

When the docs and the SDKs disagree, this page wins.

Project (Tenant)​

The unit of isolation for jobs, API keys, quotas, billing, and audit logs. One organization typically maps to one Project. All API requests are scoped to exactly one Project, resolved from the bearer API key.

  • Code field: ProjectId (UUID, tenant.id in OpenTelemetry spans).
  • Span attributes: tenant.id, tenant.plan.
  • Prose preference: "project-scoped" (not "per-tenant"). The wire protocol uses project; tenant is an internal term.

Example: POST /flare/v1/jobs always creates a job inside the Project that owns the API key on the request.

Job​

A single unit of background work. Immutable once enqueued — payload, target type, and attempt limits are fixed at creation time. Each job has a lifecycle state (see JobState).

States: Pending → Processing → Succeeded | Failed | DeadLettered | Cancelled.

  • API resource: GET /flare/v1/jobs/{id}.
  • Identifier prefix: job_ followed by a 26-character ULID (e.g. job_01HXYZ...).
  • See: Jobs API, IJob<T>.

Example: enqueue with POST /flare/v1/jobs and a JSON body specifying type, payload, optional queue, and optional idempotency_key.

RecurringJob​

A cron-based schedule that automatically enqueues Job instances on a fixed cadence. Schedules are upserted by ID (derived from the SDK class name when using [JobConfig(CronSchedule = "...")]).

  • API resource: GET /flare/v1/recurring.
  • Identifier prefix: rjob_ followed by the schedule slug (e.g. rjob_CleanupExpiredSessions).
  • See: Recurring API, Recurring Jobs guide.

Example: a [JobConfig(CronSchedule = "0 3 * * *")] annotation on CleanupExpiredSessionsJob enqueues that job at 03:00 UTC daily.

Worker​

A process — typically your application or a dedicated worker pool — that polls Flare for jobs, executes them, and acknowledges success/failure. Workers identify themselves with a stable worker_id so the dashboard can attribute throughput.

  • API resource: POST /flare/v1/workers/poll, POST /flare/v1/workers/ack.
  • See: Workers API.

Example: a Kubernetes deployment with 4 replicas of my-app-worker shows up as 4 distinct worker_ids in /flare/v1/metrics/queues.

Queue​

A named bucket inside a Project that groups jobs by routing/priority. Each Job belongs to exactly one queue. The default queue is "default".

Example: route long-running PDF renders to queue: "renders" and keep latency-sensitive emails on queue: "emails" so a slow render never starves the inbox.

API Key​

A project-scoped credential used to authenticate every API request. Stored hashed; the plaintext is shown exactly once at create/rotate time.

  • Prefix conventions: zf_live_sk_* (production), zf_test_sk_* (test/development), zf_sandbox_sk_* (planned public sandbox).
  • 24-character prefix is non-secret and is logged with each request for audit. Anything after the prefix is the secret.
  • See: Authentication, Projects API.

Example: Authorization: Bearer zf_live_sk_a1b2c3d4e5f6g7h8i9j0k1l2_<secret>.

Webhook​

Outbound HTTP callbacks fired on job lifecycle events (job.succeeded, job.failed, job.dead_lettered, etc.). Every webhook payload is HMAC-SHA256 signed with the subscription's current secret; secret rotation publishes both the new and previous signatures during a 24-hour grace window so subscribers can validate either.

Example: subscribe https://my-app.example.com/hooks/flare to job.failed and verify each delivery against the secret you received at subscription time.

Idempotency-Key​

An RFC 7231 HTTP request header for safe retry of mutating operations. Flare stores (ProjectId, Key) for 24 hours; a replay returns the original response status (e.g. 201 Created) plus an Idempotent-Replay: true header. A mismatched body on the same key returns 409 idempotency_key_reuse.

Example: a retried POST /flare/v1/jobs with the same Idempotency-Key: 6f2e... returns the original 201 and the original job.id instead of creating a duplicate.

Job Continuation​

A job that auto-enqueues when its parent finishes (Succeeded or Failed depending on the trigger). Useful for fan-out and step-functions-style pipelines.

Example: a ResizeImage job's OnSucceeded continuation enqueues UploadToCdn only if the resize step finished cleanly.

Dead Letter​

A Job that has exhausted all retry attempts (MaxAttempts) and has been moved into the DeadLettered terminal state. Dead-lettered jobs are retained for inspection but are not retried automatically.

Example: a job with MaxAttempts = 3 that fails on every attempt lands in DeadLettered after the third failure and emits a job.dead_lettered webhook.

Rate Limit​

A per-project request budget enforced by the API gateway. When exceeded, the API returns 429 Too Many Requests with a Retry-After header. Limits are plan-scoped.

Example: the Starter plan permits 60 enqueues/second; bursting past the limit returns 429 rate_limit_exceeded with Retry-After: 1.

Parameter Naming by SDK​

Each SDK uses its language's idiomatic casing. The wire format on the HTTP API is always snake_case.

ConceptWire (HTTP).NETTypeScriptPythonGoJavaPHPRuby
API keyapi_keyApiKeyapiKeyapi_keyAPIKeyapiKeyapiKeyapi_key
Idempotency keyidempotency_keyIdempotencyKeyidempotencyKeyidempotency_keyIdempotencyKeyidempotencyKeyidempotencyKeyidempotency_key
Max attemptsmax_attemptsMaxAttemptsmaxAttemptsmax_attemptsMaxAttemptsmaxAttemptsmaxAttemptsmax_attempts
Job IDidIdididIDididid
Project IDproject_idProjectIdprojectIdproject_idProjectIDprojectIdprojectIdproject_id
QueuequeueQueuequeuequeueQueuequeuequeuequeue
Cron schedulecron_scheduleCronSchedulecronSchedulecron_scheduleCronSchedulecronSchedulecronSchedulecron_schedule

Go follows Go's all-caps initialisms convention (APIKey, ID); the rest follow each language's standard casing.

See also​