# Add Rate Limiting to a Ktor API

Yes. An agent installs Ktor's RateLimit plugin on your write routes with limits from application.yaml, tests the 429 with testApplication, and opens a PR.

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

## What the agent does

The agent reads the build and the routing before it adds a plugin, because Ktor's rate limiter is a separate artifact and its version comes from the Gradle plugin. In an API shaped like the `postgres` sample of ktorio/ktor-samples, `build.gradle.kts` applies `io.ktor.plugin` 3.6.0 with Kotlin 2.4.20 and a JVM 17 toolchain, and depends on `ktor-server-core-jvm`, `ktor-server-content-negotiation-jvm`, `ktor-serialization-kotlinx-json-jvm`, `ktor-server-netty-jvm`, `ktor-server-config-yaml` and the `postgresql` 42.7.8 driver, with `ktor-server-test-host-jvm` and `kotlin-test-junit` for tests. `src/main/resources/application.yaml` names the module `com.example.PostgresApplicationKt.module` on port 8080. `PostgresApplication.kt` calls `configureSerialization()` and `configureRouting(dbConnection = connectToPostgres(embedded = false))`, and `plugins/Routing.kt` defines `POST /articles`, `GET /articles/{id}`, `PUT /articles/{id}` and `DELETE /articles/{id}` over an `ArticleService` that runs plain JDBC statements.

It adds `implementation("io.ktor:ktor-server-rate-limit")` to `build.gradle.kts`, unversioned like the other Ktor artifacts so the plugin's BOM pins it. A new `plugins/RateLimiting.kt` installs `RateLimit` with two providers: `global` for every request and a named `writes` provider for the mutating routes, each with `rateLimiter(limit, refillPeriod)` read from a new `ratelimit` block in `application.yaml` so the numbers are configuration, not constants. In `Routing.kt` the `POST`, `PUT` and `DELETE` routes move inside `rateLimit(RateLimitName("writes")) { ... }` and the `GET` stays under the global limit only. The key is the client address from `call.request.origin.remoteHost`, which the pull request notes should become the forwarded address behind a proxy, with the `ForwardedHeaders` plugin.

The sample has no tests of its own, so the agent writes the first one in the shape the `jwt-auth-tests` sample uses: `src/test/kotlin/com/example/RateLimitTest.kt` with `testApplication`, `MapApplicationConfig` to set a limit of two per minute, and the test client. Because `module()` opens a JDBC connection, the test calls `configureSerialization()`, `configureRateLimiting()` and `configureRouting()` with a stub `Connection` rather than the Postgres from `docker-compose.yaml`. It sends three `POST /articles` and asserts the third is `429 Too Many Requests` with `Retry-After` and `X-RateLimit-Remaining: 0`, then sends three `GET /articles/1` and asserts none is `429`.

Before pushing, the agent runs `./gradlew clean check --console=plain`, the command `build-all.sh` and the `Build All Samples` workflow run for every sample, with the Gradle 9.2.1 wrapper the repository ships, and pastes the test report. It also starts the app once with the `docker-compose.yaml` Postgres and shows a `curl` loop hitting `POST /articles` until the `429` appears.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add rate limiting to this Ktor API and open a pull request. Read build.gradle.kts, gradle.properties, src/main/resources/application.yaml, src/main/kotlin/com/example/PostgresApplication.kt, src/main/kotlin/com/example/plugins/Routing.kt, src/main/kotlin/com/example/service/ArticleService.kt and docker-compose.yaml first. Add io.ktor:ktor-server-rate-limit to build.gradle.kts, unversioned like the other Ktor artifacts. Add plugins/RateLimiting.kt that installs RateLimit with a global provider and a named writes provider, both with limit and refill period read from a ratelimit block in application.yaml, keyed by the client address. Wrap POST, PUT and DELETE /articles in rateLimit(RateLimitName(\"writes\")) and leave GET under the global limit. Add src/test/kotlin/com/example/RateLimitTest.kt using testApplication and MapApplicationConfig with a limit of two: three POST /articles return 429 on the third with Retry-After and X-RateLimit-Remaining headers, three GET /articles/1 never return 429. Use a stub java.sql.Connection in the test instead of Postgres. Run ./gradlew clean check --console=plain and paste the output in the pull request, then start the app with the docker-compose Postgres and show a curl loop reaching the 429. Do not change ArticleService or the existing route paths.",
  "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

What comes back is a pull request with one new dependency in `build.gradle.kts`, `plugins/RateLimiting.kt`, a `ratelimit` block in `application.yaml`, the `rateLimit` wrapper around the three write routes in `Routing.kt`, a call to `configureRateLimiting()` in `PostgresApplication.kt`, and `src/test/kotlin/com/example/RateLimitTest.kt`. The description shows the Gradle test report, the `429` response with its headers from the `curl` loop, and the limits chosen.

On a repository with the `Build All Samples` workflow, the pull request triggers `./build-all.sh`, which runs `./gradlew clean check` for the sample on JDK 24, so the new test runs on the pull request. The detekt workflow scans the new Kotlin file too.

A reviewer checks that the limiter is keyed by client address and that the key will be the forwarded address once `ForwardedHeaders` is installed behind a proxy, that `GET` reads are not throttled by the `writes` provider, that the limits in `application.yaml` match what the service can take, and that the `429` carries `Retry-After` so clients can back off. Then they set production values in the deployment's config.

## Run it on every service exposed to the public internet

A team with several Ktor services sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own `Routing.kt`, so a service with an authenticated `/login` route gets a tighter named provider on it, and each run opens its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with the `session_url` to read the pull request from, so the chosen limits can be reviewed across services at once.

## Why run it on Rush?

Rate limiting is cheap to add and easy to get wrong: throttling reads along with writes, keying by the proxy's address, or choosing a limit no one ever tested. In a Rush sandbox the agent installs the plugin against the pinned Ktor 3.6.0, writes the `testApplication` case, runs the Gradle wrapper the repository ships, and keeps every command and the `429` response in the run's record, so the pull request shows the limiter working.

The sample has no test suite today, and a first test is the part most people skip. The agent writes it in the style the sibling `jwt-auth-tests` sample uses, so the next contributor has a pattern to follow, and the same request works unchanged on every Ktor service a team owns.

## Frequently asked questions

### Does it add a dependency?

One: `io.ktor:ktor-server-rate-limit`, a first-party Ktor artifact pinned by the `io.ktor.plugin` BOM already in `build.gradle.kts`, so no version string is added.

### Why two providers?

Reads are cheap and writes hit Postgres through `ArticleService`, so they get different budgets. The global provider protects every route, and the named `writes` provider wraps `POST`, `PUT` and `DELETE /articles` with a smaller limit.

### How does the test avoid Postgres?

`module()` opens a JDBC connection, so the test calls the plugin functions directly with a stub `java.sql.Connection` whose statements return nothing. The `429` comes from the plugin before the handler runs, so the stub is never exercised for the throttled request.

### What about requests behind a load balancer?

The limiter keys by `call.request.origin.remoteHost`, which behind a proxy is the proxy. The pull request notes that installing Ktor's `ForwardedHeaders` plugin makes `remoteHost` the client address, but leaves that for the reader because trusting forwarded headers depends on their network.

## More Ktor jobs

- [Add Request ID Logging to a Ktor Server](https://getrush.ai/run/add-request-id-logging/ktor/)
- [Add Structured JSON Logging to a Ktor Server](https://getrush.ai/run/add-structured-logging/ktor/)
- [Dockerize a Ktor Server](https://getrush.ai/run/dockerize-app/ktor/)

## The same job on other stacks

- [Add Rate Limiting to a LangGraph Agent](https://getrush.ai/run/add-rate-limiting/langgraph/)
- [Add Rate Limiting to a Leptos Server](https://getrush.ai/run/add-rate-limiting/leptos/)
- [Add Rate Limiting to a Litestar API](https://getrush.ai/run/add-rate-limiting/litestar/)

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