Getting started

Introduction

Halyard runs your background work. Queue a job with one request, schedule recurring tasks, fan out events and let failed work retry itself.

On this page

What is Halyard?
Your first request
Core concepts
Next steps

What is Halyard?

Most apps have work that shouldn't happen inside a web request: sending email, resizing images, syncing with another service, building a report at midnight. Halyard takes that work off your servers' critical path. You describe a job, Halyard stores it durably, runs it on your workers and tells you how it went.

Durable by default. Every job is written to three zones before the API answers.
Retries built in. Failed jobs back off and try again, up to the limit you set.
Observable. Every attempt, log line and duration is kept for 30 days.

Your first request

Create a job by naming a queue, a task and a payload. The response comes back in a few milliseconds with the job's ID; your worker picks it up as soon as it is free.

Create a job

curl https://api.halyard.example/v3/jobs \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \  -H "Content-Type: application/json" \  -d '{    "queue": "emails",    "task": "send-welcome-email",    "payload": { "user_id": "usr_8KfQ2" }  }'

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const job = await halyard.jobs.create({  queue: "emails",  task: "send-welcome-email",  payload: { user_id: "usr_8KfQ2" },}); console.log(job.id); // job_3Rk9Tq7Xw2

from halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) job = halyard.jobs.create(    queue="emails",    task="send-welcome-email",    payload={"user_id": "usr_8KfQ2"},) print(job.id)  # job_3Rk9Tq7Xw2

Core concepts

Four ideas cover almost everything Halyard does.

JobsA unit of work with a task name, a payload and a lifecycle you can follow.QueuesNamed lanes that control concurrency, priority and rate per kind of work.RetriesExponential backoff with jitter, a maximum attempt count and dead letters.SchedulesCron expressions with time zones for work that repeats.

Next steps

Follow the Quickstart to run a worker locally in five minutes, or jump straight to the API reference if you already know what you need.