Hen

Hen is an API testing framework and collection runner. Define requests, assertions, captures, and dependencies in a .hen file, then run the same collection in the terminal, in CI, and in editor-assisted workflows.

Why teams reach for Hen

• Keep requests, assertions, captures, and dependencies together in plain text.
• Verify collections structurally before any network calls or shell callbacks run.
• Reuse the same collection for local exploration, automation, and version-controlled collaboration.
• Author HTTP, GraphQL, SSE, and WebSocket flows in one format.
• Import OpenAPI 3.x specs into editable .hen starter collections instead of rewriting contracts by hand.

A single file can express the workflow

name = Create export and wait

$ API_ORIGIN = https://api.example.com
$ API_TOKEN = secret.env("HEN_API_TOKEN")

---

Create export

POST {{ API_ORIGIN }}/exports
* Authorization = Bearer {{ API_TOKEN }}

^ & status == 202
& body.jobId -> $JOB_ID

---

Wait for export

> requires: Create export
GET {{ API_ORIGIN }}/exports/{{ JOB_ID }}
poll_until = 2m
poll_every = 2s

^ & status == 200
^ & body.state == "completed"

The same collection can now be:

• run interactively from the terminal
• executed non-interactively in CI
• inspected by editor tooling

Hen can also generate that starting collection from an OpenAPI contract:

hen import ./openapi.yaml --output ./api.hen

What Hen is good at

• Replacing ad hoc curl scripts with reusable workflows
• Turning exploratory request collections into CI checks
• Keeping assertions close to the requests they validate
• Reusing captured values, cookies, prompts, and environments across related requests
• Giving editor tooling a machine-readable view of the same collection

Choose your path

If you want to...	Start here
Try Hen from the terminal	Getting Started
Start from an OpenAPI spec	CLI Guide
Learn the authoring syntax quickly	Syntax Cheatsheet
Learn the day-to-day commands	CLI Guide
Look up flags and command syntax	CLI Reference
Run collections in scripts or CI	CI and Automation
Copy a working pattern	Recipes
Look up exact syntax	Reference

Core mental model

• A .hen file is executable API workflow source code.
• Variables and prompts define reusable inputs.
• Assertions validate each request inline.
• Captures and sessions let later requests build on earlier ones.
• run, verify, and inspect are different ways to use the same collection.

Where Hen fits

Hen sits between raw HTTP tooling and heavyweight API platforms:

• more reusable than one-off shell commands
• more automation-friendly than GUI-only request tools
• more structured than stitching together ad hoc scripts
• easier to expose to editors and agents than homegrown request runners

Canonical sources

The repository root README.md and syntax-reference.md remain the canonical long-form sources. The website reorganizes that material into task-oriented pages for day-to-day use.