# Add a Health Check Endpoint to a Litestar App

Yes. An agent adds GET /health to a Litestar app, answered on the loop and kept out of the OpenAPI schema, with a TestClient test, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-health-checks/litestar/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

A health route in Litestar is a handler and a registration, but the project's tooling decides how it has to be written, so the agent reads that tooling first. In an app laid out like litestar-org/litestar-hello-world, `app.py` defines two handlers with `@get`: `async_hello_world` on `/async`, which awaits `asyncio.sleep(0.1)`, and `sync_hello_world` on `/sync` with `sync_to_thread=False`, so Litestar runs the plain function on the event loop instead of a worker thread. Both return `Dict[str, Any]` with a `# noqa: UP006` because `pyproject.toml` sets `target-version = "py38"` for Ruff while selecting every rule with `select = ["ALL"]`, and the module declares `__all__ = ("async_hello_world", "sync_hello_world")`. `app = Litestar(route_handlers=[sync_hello_world, async_hello_world])` is the whole application. `pyproject.toml` depends on `litestar[standard]>=2.4.1`, resolved to `2.4.1` in `pdm.lock`, supports Python 3.8 through 3.12 and runs mypy in strict mode. `tests/test_app.py` has two tests that open `TestClient(app=app)` and assert the JSON of each route.

The checks that run on a pull request are in `.pre-commit-config.yaml` and `.github/workflows/ci.yaml`. The hooks include `ruff` with `--fix` and `ruff-format`, `codespell`, `mypy` with `litestar[standard]` as an additional dependency, `slotscheck`, and `ensure-dunder-all` from `flake8-dunder-all` with `--use-tuple`, which fails if a public name is missing from `__all__`. The workflow runs those hooks on Python 3.11, then the `test.yaml` reusable workflow on 3.8 through 3.11 with coverage on 3.11, and on macOS and Windows for pushes. `pdm.lock` is checked by a `pdm-lock-check` hook, so a dependency change without a lock update fails too. None of this is visible from `app.py`, and a handler written without the `noqa`, the tuple entry or the right annotation style fails before a test runs.

The agent adds `health` to `app.py`: `@get("/health", sync_to_thread=False, include_in_schema=False)` on a plain function returning `Dict[str, str]` with `{"status": "ok"}`, since a health probe should not take a thread from the pool or appear in the `/schema` documentation Litestar generates by default. The response carries `Cache-Control: no-store` through the handler's `response_headers` so a proxy never answers a probe from cache. The name joins the `__all__` tuple and the handler joins `route_handlers`. For an app with a database or a cache, the same handler would call each dependency and answer 503 with the failing name through a `Response` with `status_code`; this app has neither, and the pull request says where that check goes when one arrives. A second route is not added for readiness; a single `/health` matches what the app can report.

Then the agent runs what CI runs. It installs PDM, runs `pdm install` to get the locked `litestar` and the `lint` and `test` groups, and `pdm run lint`, which is `pre-commit run --all-files`, so Ruff, mypy, codespell and the `__all__` hook all pass on the new code. It adds `test_health` to `tests/test_app.py` beside `test_sync` and `test_async`, asserting the status, the JSON and the `Cache-Control` header through `TestClient`, and a second test that reads `/schema/openapi.json` and asserts `/health` is not among its paths. It runs `pdm run test` and `pytest tests --cov` as the `Makefile`'s `coverage` target does, and starts the app once with `litestar run` from the `[standard]` extra's CLI to request `/health` with `curl` as the README does for `/sync` and `/async`.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a health check endpoint to this Litestar app. Read app.py, tests/test_app.py, pyproject.toml, pdm.lock, .pre-commit-config.yaml, .github/workflows/ci.yaml, .github/workflows/test.yaml, the Makefile and README.md first. Add a GET /health handler in app.py with sync_to_thread=False and include_in_schema=False that returns {\"status\": \"ok\"} with a Cache-Control: no-store response header, annotated in the same Dict style as the existing handlers with the noqa the Ruff target needs, added to __all__ and to route_handlers. Add tests in tests/test_app.py for the status, body and header, and one that checks /health is absent from /schema/openapi.json. Install PDM, run pdm install, pdm run lint, pdm run test and pytest tests --cov, start the app with litestar run and request /health with curl, and open a pull request that shows the response and the lint and test output. Do not change pyproject.toml or pdm.lock.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `app.py` and `tests/test_app.py` and nothing else. Its description shows the `curl` response with its headers, the `pre-commit run --all-files` output with every hook passing, and the pytest summary with the new tests, and explains why the route skips the thread pool and the OpenAPI schema.

The `Tests and Linting` workflow runs on the pull request: the `validate` job runs the same hooks on 3.11, and the `test` job runs the suite on 3.8 through 3.11, so the `Dict` annotation and the `noqa` are checked on the oldest version the project supports. The run's record keeps the sandbox output for comparison with those checks.

Before merging, a reviewer decides whether `/health` should also answer `HEAD` for a load balancer that probes that way, whether to keep it out of the schema or document it, and where a dependency check goes once the app has a database. `pyproject.toml`, `pdm.lock` and the two existing routes are unchanged.

## Run it on every Litestar service without a health route

An organisation with several Litestar services starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own app, so a service built on the Litestar fullstack template with a database plugin gets a handler that pings the engine, and one with a `Router` prefix gets the route registered under it.

A team that files platform work as Linear issues runs this prompt from an automation in the Project with a `linear` trigger on issues labelled `platform`. The trigger adds the issue after the prompt, so an issue that names the probe path a Kubernetes manifest expects, or asks for separate liveness and readiness routes, reaches the agent with those names, and the pull request links back to it.

## Why run it on Rush?

The handler is four lines, and every one of them is checked by a tool that does not run from the editor: Ruff with every rule on, mypy strict, a hook that fails when `__all__` is missing a name, and a test matrix down to Python 3.8 where `dict[str, str]` in an annotation is a syntax the project avoids. The agent runs the same hooks and the same suite in its own sandbox through PDM, so the pull request arrives green rather than with a lint failure to fix first.

Every command stays with the run, from `pdm install` to the `curl` against `litestar run`, so a reviewer sees the response before merging. The same prompt runs across every Litestar service at once, each in its own sandbox and with its own pull request.

## Frequently asked questions

### Why sync_to_thread=False on the health handler?

A plain `def` handler runs in a worker thread by default so it cannot block the loop, and Litestar warns when the setting is left implicit. A health probe does no I/O and returns a constant, so running it on the loop like `sync_hello_world` avoids a thread hop for something a load balancer calls every few seconds.

### Why keep it out of the OpenAPI schema?

Litestar serves generated documentation at `/schema` for every route unless `include_in_schema=False`. A probe is for infrastructure, not for API clients, so leaving it out keeps the documentation about the service's actual surface. A team that wants it listed removes one argument.

### What does a health check look like once the app has a database?

The same handler becomes `async`, awaits a cheap query through the app's engine or a `ping` on the cache, and returns a `Response` with status 503 and the failing dependency's name when one raises. The pull request names that spot so the next change goes in the right place.

### Will the test matrix accept the new code on Python 3.8?

Yes, as long as the annotation uses `Dict` from `typing` with the `noqa: UP006` the existing handlers carry, which is why the agent copies their style instead of writing `dict[str, str]`. The `test` job runs on 3.8 first, so a slip shows in CI as well as in the sandbox.

## More Litestar jobs

- [Add JWT Authentication to a Litestar App](https://getrush.ai/run/add-jwt-authentication/litestar/)
- [Add OpenTelemetry Tracing to a Litestar App](https://getrush.ai/run/add-opentelemetry/litestar/)
- [Add Prometheus Metrics to a Litestar App](https://getrush.ai/run/add-prometheus-metrics/litestar/)

## The same job on other stacks

- [Add Health Checks to an Express and Mongoose API](https://getrush.ai/run/add-health-checks/mongoose/)
- [Add Health Checks to a NestJS API](https://getrush.ai/run/add-health-checks/nestjs/)
- [Add a Health Check Endpoint to a Node.js App](https://getrush.ai/run/add-health-checks/nodejs/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
