Hurl for coding agents

When a coding agent changes an HTTP endpoint, a URL where a service accepts requests, the agent needs a way to send a request and check the response. Hurl runs requests described in plain-text files and checks whether the responses match expectations, such as a status code, a header, or a value in the response body. An agent can use it to add a repeatable API check to a code change, then run that check from the shell.

Hurl files can contain several requests. Hurl runs entries in a file in order, so a later request can reuse a value saved from an earlier response. The request file stays in the code repository, where a developer can review and edit it alongside the code. The Hurl project documents the command-line tool and its request format.

Install and check Hurl

On macOS with Homebrew installed, install Hurl with:

brew install hurl
hurl --version

The first command installs Hurl. The second prints its version so you can confirm the shell can find the command. For other platforms, use the packages or release binaries listed in the official repository.

Hurl does not require an account to send a request to a public endpoint. For a protected API, requests need whatever credentials that API requires. Hurl supports variables, including values supplied with --variable or --variables-file; keep credentials in a local secret store or ignored file rather than putting them in an agent prompt or a committed request file. The running-tests documentation describes these options.

Add a read-only request check

A coding agent can send a GET request, an HTTP request that asks a server to return data, to check that an endpoint responds successfully. Create a file named health.hurl:

GET https://example.com
HTTP 200
[Asserts]
header "Content-Type" contains "text/html"

The first line sends an HTTP GET request to the public example domain. The HTTP 200 line expects a successful status code. The assertion, a check on the response, verifies that the response’s Content-Type header includes text/html.

Run the file in test mode:

hurl --test health.hurl

Hurl reports whether the request and its assertions pass or fail. When you run the local request file, Hurl sends a network request to the remote server at example.com. This example sends a GET request and does not ask the server to create or update data. Hurl’s test-running options also include report formats such as JUnit and HTML for automated test runs.

An agent prompt for this task could be:

Add health.hurl with a GET request to the documented health endpoint. Assert the expected status and response header, then run hurl --test health.hurl. Do not send credentials or change server data. Report the file you added and whether the check passed.

Use the service's documented URL in the example and its documented header in the assertion. If the endpoint only exists on a local development server, start that server separately and target its local address. Hurl sends requests to the URL in the file; it does not start the service for you.

Use Hurl for API changes

For a real code change, the agent can add a Hurl request that exercises the changed route, then assert the contract the route should preserve. A contract is the behavior clients should see when they send HTTP requests, such as a particular status code and a required response field. Hurl checks response status codes, headers, and bodies. For JSON responses, it also supports JSONPath queries, which select values from the response. Its documentation covers request chaining and capturing response values for later requests.

Hurl sends real HTTP requests to the configured target. A request that creates or deletes data changes that service, so use a local test service or a dedicated test environment for those checks. Hurl does not turn a live endpoint into a mock. For a safe first check, use a known read-only route and verify the URL before asking an agent to run it.

Hurl fits shell-based agent work because the request and assertions are readable text, and the same command can run locally or in a CI job. Hurl needs an HTTP service it can reach to run request-based checks. If the service is offline, the agent cannot use Hurl to validate that endpoint’s live response.