# Inventory Every API Endpoint of an Axum Service

Yes. An agent reads your Axum routers and extractors and writes a table of every endpoint with its method, handler, auth rule, query parameters and error codes.

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

## What the agent does

The agent clones the service and starts where the routes are assembled. In a service shaped like launchbadge/realworld-axum-sqlx, `src/http/mod.rs` holds `serve()`, which takes an `api_router()` built from `users::router().merge(profiles::router()).merge(articles::router())`, wraps it in a `ServiceBuilder` with an `AddExtensionLayer` carrying the `ApiContext` (the `Config` and the `PgPool`) and a `TraceLayer::new_for_http()`, and binds `0.0.0.0:8080`. `Cargo.toml` pins `axum` 0.3.4, `sqlx` 0.5 on Postgres, `tower-http` 0.2 and `jwt` 0.15, and `src/main.rs` reads `DATABASE_URL` and `HMAC_KEY` through the `clap`-derived `Config`, opens a pool of at most 50 connections and runs `sqlx::migrate!()` before serving. The agent records that mount map first, because it tells a reader which layers every route passes through.

Then it walks each router. `src/http/users.rs` registers `POST /api/users`, `POST /api/users/login` and `GET` plus `PUT /api/user`; `profiles.rs` registers `GET /api/profiles/:username` and `POST` plus `DELETE /api/profiles/:username/follow`; `articles/mod.rs` registers `/api/articles` with `POST` and `GET`, `GET /api/articles/feed`, `GET`, `PUT` and `DELETE /api/articles/:slug`, `POST` and `DELETE /api/articles/:slug/favorite`, `GET /api/tags`, and merges `comments::router()` with `GET` and `POST /api/articles/:slug/comments` and `DELETE /api/articles/:slug/comments/:comment_id`. For each registration it reads the handler's signature: a handler that takes `AuthUser` requires a token, one that takes `MaybeAuthUser` accepts an optional one, and one that takes neither is public. `src/http/extractor.rs` defines both: `AuthUser` parses an `Authorization: Token <jwt>` header, verifies it with HMAC-SHA-384 under `HMAC_KEY`, rejects an expired `exp` claim, and answers `Error::Unauthorized` on any failure; `DEFAULT_SESSION_LENGTH` is two weeks.

The agent also captures what each endpoint takes and returns. `articles/listing.rs` declares `ListArticlesQuery` with `tag`, `author`, `favorited`, `limit` and `offset`, and `FeedArticlesQuery` with `limit` and `offset`; `users.rs` answers `422` through `Error::unprocessable_entity` with field errors such as `username taken` and `email taken`; `profiles.rs` maps the `user_cannot_follow_self` constraint to `Error::Forbidden` with `on_constraint`; `articles/mod.rs` returns `Forbidden` when a user edits or deletes another author's article and `NotFound` for an unknown slug. `src/http/error.rs` maps the `Error` enum to status codes: `Unauthorized` is 401, `Forbidden` 403, `NotFound` 404, `UnprocessableEntity` 422 and `Sqlx` or `Anyhow` 500. Each row in the inventory cites the file and line the fact came from.

It writes the result as `endpoints.md` in the sandbox: the mount map, one table per router with method, path, handler, auth rule, request and query fields, response body and error codes, and a closing section that lists what it could not settle from the code alone, such as whether `TraceLayer` logging is enabled in production (`RUST_LOG=tower_http=debug` per the comment in `mod.rs`). Before writing, it runs `cargo build` to make sure the handler names it cites exist on the branch it read, and it cross-checks the table against `.github/workflows/rust.yml`, which runs the upstream Realworld Postman collection against `http://localhost:8080/api`, so any route the collection calls that the table lacks is flagged.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Write an inventory of every HTTP endpoint in this Axum service as endpoints.md. Start from src/http/mod.rs: describe api_router(), the layers in serve() (AddExtensionLayer with ApiContext, TraceLayer) and the bind address. Then read src/http/users.rs, src/http/profiles.rs, src/http/articles/mod.rs, src/http/articles/listing.rs, src/http/articles/comments.rs, src/http/extractor.rs and src/http/error.rs. For every .route() registration write a row with method, path, handler function, auth rule (none, MaybeAuthUser or AuthUser), request body and query struct fields, response body type and the Error variants the handler can return with their status codes from error.rs. Group the rows by router. Cite file and line for every row. Add a section on how AuthUser parses and verifies the Authorization header and how long a token lives. End with a list of anything you could not settle from the code. Run cargo build first so every handler name you cite exists. Do not change any file.",
  "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 one file, `endpoints.md`, as an artifact on the session, with a download link that works for an hour and is refreshed on every read of the session. Its first part is the mount map from `mod.rs`: the three merged routers, the extension layer that gives every handler the pool and config, the trace layer, and the port. Then come the tables, one per router, each row carrying method, path, handler, auth rule, the request and query fields, the response type and the error variants with their status codes, with a `file:line` citation.

The session's `result` field holds the agent's summary: how many routes it found, which are public, optional-auth and token-only, and what it flagged at the end. The transcript at `GET /o/{org}/sessions/{id}/messages` shows every `cargo build` and file read as `tool_use` events, so a reader can confirm the table was built from the code and not from the README's description of the Realworld spec.

A reviewer checks the table against the router files, the auth column against the extractor types, and reads the final section: a route the Postman collection calls that the table lacks, or a handler whose error path is not mapped in `error.rs`, is a finding worth a ticket. The file goes into the repository or a wiki by hand; the run writes nothing to the branch.

## Run it on every pull request that touches a router

Add an automation to the Project with this prompt and a `github` trigger on `pull_request.opened` and `pull_request.synchronize` with `branch_patterns` set to `main`. A trigger filters on branch, labels and authors, not on paths, so the prompt tells the agent to end with a one-line result when the diff touches none of `src/http/mod.rs`, `users.rs`, `profiles.rs`, `extractor.rs`, `error.rs` or the `articles` directory. The trigger adds the pull request event after the prompt and fills in nothing; pull requests from forks never fire it.

For a standing inventory, a `schedule` trigger with `cron` set to the first of the month regenerates it, or a release script sends `POST /o/{org}/sessions` with this body and a `request_id` that is a UUID v5 of the tag, so a rerun returns the same run. Give the key a `webhook_url` and Rush POSTs `run.completed` with `data.session_url` to read for the artifact.

## Why run it on Rush?

An Axum inventory is a cross-reference job: the route table is in one file, the auth rule is in the extractor each handler asks for, the query fields are in a `serde` struct two files away, and the status codes are in a `match` in `error.rs`. Doing it by hand means holding six files open and still missing the handler that returns `Forbidden` on a constraint name. In a Rush sandbox the agent reads every file, runs `cargo build` so the names it cites compile, and keeps each read in the run's record, so the table carries its own evidence.

Because the run needs only the repository and no running database, it finishes with a file and a summary rather than a branch, and the same request can run against several Axum services at once, each in its own sandbox, each returning its own `endpoints.md`.

## Frequently asked questions

### How does the agent know which routes need a token?

From the handler signature. In this codebase a handler that takes `AuthUser` cannot run without a valid `Authorization: Token` header, because the extractor returns `Error::Unauthorized` first; one that takes `MaybeAuthUser` runs with or without it and gets `None` when absent. The inventory reports that column from the extractor types rather than from comments.

### Does it cover routes added by a layer or middleware?

It reports the layers in `serve()` and says what they do: the extension layer injects state and `TraceLayer` logs requests. Neither adds a route. A middleware that answered requests itself would be listed in the mount map with the paths it intercepts.

### Will it run the Postman collection from CI?

No. The collection needs a Postgres service and the upstream Realworld checkout that `rust.yml` performs. The agent reads the workflow to learn which paths the collection exercises and compares them with the table; running them is a separate job.

### Can the output be JSON instead of Markdown?

Yes. Ask for `endpoints.json` with the same columns in the prompt, or for both. Each file the agent writes becomes an artifact on the session with its own `name`, `mime_type` and download `url`.

## More Axum jobs

- [Dockerize an Axum API With SQLx and Postgres](https://getrush.ai/run/dockerize-app/axum/)
- [Review SQLx Migrations in Axum Pull Requests](https://getrush.ai/run/review-database-migrations/axum/)
- [Upgrade Axum and Cargo Dependencies](https://getrush.ai/run/upgrade-cargo-dependencies/axum/)

## The same job on other stacks

- [List Every API Endpoint in an Express App](https://getrush.ai/run/api-endpoint-inventory/express/)
- [List Every API Endpoint in a FastAPI App](https://getrush.ai/run/api-endpoint-inventory/fastapi/)
- [Inventory the API Endpoints of a Gin Service](https://getrush.ai/run/api-endpoint-inventory/gin/)

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