# Add Health Check Endpoints to a Koa API

Yes. An agent adds liveness and readiness routes to your Koa API that check the database through your ORM, outside the JWT guard, with tests, in a PR.

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

## What the agent does

The agent reads how requests reach the app before it adds two routes, because in a Koa server the order of `app.use` calls decides whether a health probe gets a 200 or a 401. In an API laid out like javieraviles/node-typescript-koa-rest, `src/server.ts` opens a TypeORM 0.2 Postgres connection from `config.databaseUrl` with `synchronize: true`, then builds the app in order: `koa-helmet`'s content security policy, `@koa/cors`, a Winston logger middleware from `src/logger.ts` that times each request and catches errors into the status and body, `koa-bodyparser`, the `unprotectedRouter` from `src/unprotectedRoutes.ts` (a single `GET /` that answers a hello-world string from `src/controller/general.ts`), then `koa-jwt` with the secret from `config.jwtSecret`, excluding only `/swagger-` paths, and the `protectedRouter`, a `SwaggerRouter` from `koa-swagger-decorator` with the user routes. A `cron` job from `src/cron.ts` starts before `app.listen`. `src/config.ts` reads `PORT`, `NODE_ENV`, `JWT_SECRET` and `DATABASE_URL` from `.env`, and `.example.env` documents them. `package.json` pins Koa 2.13, TypeScript 4.2, Jest 26 with `ts-jest`, and `engines` says Node 14; `Dockerfile` builds on `node:14-alpine` and exposes 3000, `docker-compose.yml` runs Postgres 10 and Adminer, and the tests under `tests/` mock `typeorm` and `class-validator` per file.

The agent adds `src/controller/health.ts` with two static methods in the style of `general.ts`, decorated for Swagger. `live` answers 200 with `{"status": "ok"}` and the uptime, and nothing else, because a liveness probe that touches the database restarts a healthy process during a database outage. `ready` runs `SELECT 1` through `getConnection().query()` with a short timeout, and answers 200 with `{"status": "ok", "database": "ok"}` or 503 with the failure named, so a load balancer stops routing to an instance that cannot serve. Both are registered on `unprotectedRouter` as `GET /health/live` and `GET /health/ready`, which places them before the JWT middleware, so no token is needed and the existing `.unless()` list stays as it is.

The logger middleware logs every request at `info`, which makes a probe every few seconds the loudest thing in the log, so the agent adds a check in `src/logger.ts` that logs `/health/` paths at `debug`. `Dockerfile` gets a `HEALTHCHECK` that curls `/health/live` on port 3000, and `README.md` gets a short section under the endpoints that says what each route answers and which one a probe should use.

To check it, the agent writes `tests/controller/health.test.ts` in the same shape as `tests/controller/user.test.ts`, mocking `typeorm` so `getConnection().query` resolves for one case and rejects for another, and asserts the status and body of both methods. It runs `npm run lint`, which also type-checks, `npm test`, and `npm run build`, and starts the server against a Postgres it runs in its sandbox to request both routes with `curl`, once with the database up and once after stopping it, pasting the four responses into the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add health check endpoints to this Koa API. Read src/server.ts, src/config.ts, src/logger.ts, src/unprotectedRoutes.ts, src/protectedRoutes.ts, src/controller/general.ts, src/controller/index.ts, src/cron.ts, package.json, tsconfig.json, Dockerfile, docker-compose.yml, .example.env, tests/controller/user.test.ts and README.md first. Add a health controller with a liveness route that touches nothing and a readiness route that runs SELECT 1 through the TypeORM connection with a timeout and answers 503 when it fails, register both on the unprotected router so the JWT middleware does not guard them, log health paths at debug in the logger middleware, add a Dockerfile HEALTHCHECK on the liveness route, document both routes in the README, and write a Jest test in the style of the existing controller test that covers the database up and down. Run lint, the tests and the build in your sandbox, start Postgres and the server, curl both routes with the database up and then down, and open a pull request with the output.",
  "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 adds `src/controller/health.ts` and `tests/controller/health.test.ts` and changes `src/controller/index.ts`, `src/unprotectedRoutes.ts`, `src/logger.ts`, `Dockerfile` and `README.md`. Its description shows the four `curl` responses with their status codes, the Jest output, and the lint and build results.

The routes appear in the Swagger document the protected router generates, with the response schemas, and answer without a token. The user routes, the JWT guard, the cron job and the database configuration are unchanged, and the `CI` workflow runs the same build and test steps on the pull request.

Before merging, a reviewer decides which route the platform's probes should call and with what interval, whether the readiness route should also check anything the API depends on beyond Postgres, and whether the `HEALTHCHECK` interval in the Dockerfile matches how the image is run.

## Run it on every service without a health route

A team with several Node services sends this body once per repository to `POST /o/{org}/sessions`, each with its own 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 instead of opening a second pull request. Each run reads its own server: an Express app gets the routes before its auth middleware, a service on Mongoose gets a `ping` command instead of `SELECT 1`, and one that already answers `GET /` with a health-looking body gets that route left alone and the two new ones beside it.

A `webhook_url` on the key reports each `run.completed` with the pull request in `result`, and a `run.failed` names a service whose tests did not pass before the change, which is worth knowing on its own.

## Why run it on Rush?

Two routes are a small change, but the details are where probes go wrong: a liveness check that queries the database, a readiness route behind the token guard, a log full of probe lines, a Dockerfile that never says the container is healthy. The agent reads the middleware order and the logger, places the routes where the framework needs them, and shows the responses with the database up and down from its own sandbox.

The curl output, the tests and the build stay with the run and are pasted into the pull request, so the review is about what readiness should mean here rather than whether the routes answer. Several services can get the same two routes at once, each in its own framework's shape.

## Frequently asked questions

### Why two routes instead of one /health?

Liveness tells an orchestrator whether to restart the process; readiness tells a load balancer whether to send traffic. Folding the database check into liveness means a database outage restarts every instance, which makes the outage worse. The two routes keep those decisions apart.

### Will the JWT middleware block the probes?

No. The routes are registered on the unprotected router, which `src/server.ts` mounts before `koa-jwt`, so a request to them never reaches the guard. The `.unless()` list on the guard is unchanged.

### Does the readiness check add load to Postgres?

One `SELECT 1` per probe, on the pool TypeORM already keeps open, with a timeout so a hung connection answers 503 quickly instead of stalling the probe. At typical probe intervals that is a handful of trivial queries a minute.

### What about the log noise?

The logger middleware logs every request at `info`; the pull request logs `/health/` paths at `debug`, which `config.debugLogging` turns off outside development, so production logs show real requests only. Errors on the readiness route still log at `error`.

## More Koa jobs

- [Add Input Validation to a Koa App](https://getrush.ai/run/add-input-validation/koa/)
- [Add JWT Login to a Koa API](https://getrush.ai/run/add-jwt-authentication/koa/)
- [Add OpenTelemetry Tracing to a Koa API](https://getrush.ai/run/add-opentelemetry/koa/)

## The same job on other stacks

- [Add Health Check Endpoints to a Ktor Server](https://getrush.ai/run/add-health-checks/ktor/)
- [Add Liveness and Readiness Probes to Kustomize Manifests](https://getrush.ai/run/add-health-checks/kustomize/)
- [Add Health Checks to a Leptos App](https://getrush.ai/run/add-health-checks/leptos/)

## 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/)
