improvement(api): consolidate public v2 route handling - #6370

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 7, 2026 6:41am

PR Summary

Medium Risk
Wide refactor of the public API request pipeline (auth, rate limits, parsing order) across many v2 endpoints; behavior is intended to be equivalent but any ordering or envelope regression would affect all migrated routes.

Overview
Introduces withPublicApiRouteHandler, a shared wrapper for API-key v2 routes that runs rate limiting → v2 rollout gate → contract parsing before the route handler, and maps unexpected failures to the canonical v2 500 envelope via withRouteHandler. Auth and rate-limit denials (401/429) and the rollout gate run before the request body is read or parsed.

requireRateLimitUserId replaces unsafe userId! usage when building AuthorizedRequest after an allowed rate-limit result.

Dozens of v2 route modules (audit logs, billing, credentials, custom tools, files, knowledge, logs, MCP servers, etc.) are refactored to register only their contract, rate-limit endpoint, optional parseOptions, and business logic—removing per-route duplicate logging and try/catch. Endpoint-specific authorization (workspace access, personal-key rules, orchestration errors) stays in handlers; some routes now rethrow after mapping known errors so the wrapper handles logging.

Adds public-api-route-handler.test.ts covering short-circuit ordering, body-size options, and error envelopes.

^{Reviewed by Cursor Bugbot for commit 79177e9. Bugbot is set up for automated code reviews on this repo. Configure here.}

Greptile Summary

The PR consolidates standard public v2 route handling without leaving an eligible follow-up defect.

• Adds a shared API-key route wrapper for rate limiting, rollout gating, authentication, contract parsing, request context, and canonical unhandled-error responses.
• Migrates standard v2 endpoints while retaining endpoint-specific authorization and known-error mapping.
• Updates validation tooling and tests to recognize and exercise wrapper-based routes.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

sequenceDiagram
  participant Client
  participant Wrapper as withPublicApiRouteHandler
  participant RateLimit as API-key / rate limit
  participant Gate as v2 rollout gate
  participant Parser as Contract parser
  participant Route as Endpoint handler
  Client->>Wrapper: v2 request
  Wrapper->>RateLimit: authenticate and check limit
  RateLimit-->>Wrapper: user and rate-limit context
  Wrapper->>Gate: verify v2 access
  Gate-->>Wrapper: allowed
  Wrapper->>Parser: parse params, query, headers, and body
  Parser-->>Wrapper: typed input
  Wrapper->>Route: input and auth context
  Route-->>Wrapper: endpoint response
  Wrapper-->>Client: response with request/rate-limit headers

_{Reviews (4): Last reviewed commit: "improvement(api): consolidate public v2 ..." | Re-trigger Greptile}

@greptile

@cursor review

@greptile

@cursor review

@greptile