SDKs

Official client libraries

Thin wrappers over the same HTTP API: batching, lease extension, backoff, and nothing else.

Updated 13 August 2026API v2.4.13 languages

What a client does

Every client is the same program in three languages: it leases a batch, hands you the bodies, and acks when your handler returns. Four things are handled below the call, and everything else is the HTTP API you already have.

Handled for you
Retries429 and 503	Backoff doubles from one second and stops at five minutes. Every other code surfaces to your handler immediately, because retrying will not help.
Lease extensionhalf-timeout	One extend call per half of the visibility timeout while a handler is still running. It stops on ack, nack or a thrown error.
Batchingmax 25	One lease call per batch, long polling up to 20s, so an idle consumer holds a connection instead of spinning.
Idempotency24 hours	A publish retried after a timeout reuses its Idempotency-Key, so the message is stored once and you get the original id back.

Note

No client is required. The quickstart runs on plain curl, and a language without an official library talks to the same nine endpoints.

The same consumer, three times

One queue, batches of 25, a 20 second long poll and an ack when the handler returns. Pick a language and the page follows it.

@halyard/node 2.4.1Node 20 and Bun 1.1

The lease iterator is an async generator, so the loop ends when you break out of it and the open lease is nacked on the way out rather than left to time out.

terminalbash

bun add @halyard/node

consumer.tsts

import { Halyard } from "@halyard/node";

const halyard = new Halyard({ key: process.env.HALYARD_KEY });

for await (const lease of halyard.queue("orders").leases({
  max: 25,
  wait: "20s"
})) {
  for (const message of lease.messages) {
    await fulfil(message.body);
  }
  await lease.ack();
}

halyard 2.4.1Python 3.10 and up

The lease is a context manager as well as an iterable. Leaving the block acks it, and an exception inside the block nacks it with the exception type as the reason.

terminalbash

pip install halyard

consumer.pypython

import os
from halyard import Halyard

halyard = Halyard(key=os.environ["HALYARD_KEY"])

for lease in halyard.queue("orders").leases(max=25, wait="20s"):
    with lease:
        for message in lease.messages:
            fulfil(message.body)

halyard-go v2.4.1Go 1.22 and up

Leases arrive on a channel that closes when the context is cancelled, so a consumer shuts down on the first signal without dropping the batch it is holding.

terminalbash

go get github.com/halyard/halyard-go

consumer.gogo

client := halyard.New(os.Getenv("HALYARD_KEY"))
queue := client.Queue("orders")

for lease := range queue.Leases(ctx, halyard.Batch{Max: 25, Wait: "20s"}) {
    for _, message := range lease.Messages {
        fulfil(message.Body)
    }
    lease.Ack()
}

OpenAPI spec

halyard-openapi-2.4.1.jsonOpenAPI 3.1

The spec is generated from the same source as this reference, so it carries all nine endpoints, every parameter and every error code. It ships with each release; generate a client for anything the three libraries do not cover.

halyard-openapi-2.4.1.jsonjson

{
  "openapi": "3.1.0",
  "info": {"title": "Halyard", "version": "2.4.1"},
  "servers": [{"url": "https://api.halyard.dev/v1"}],
  "paths": {
    "/queues/{queue}/messages": {
      "post": {
        "operationId": "publishMessages",
        "security": [{"bearer": ["queues:write"]}]
      }
    }
  }
}

terminalbash

bunx @openapitools/openapi-generator-cli generate \
  -i halyard-openapi-2.4.1.json \
  -g rust -o ./halyard-rust

Download the specsoon

published with every release