v2-api-conventions

Define the route contract first in lib/api/contracts/v2/<domain>.ts, then write the application use case, then build the route with defineV2JsonRoute declaring auth, rate limit, error policy, and present. Finally add the OpenAPI description and run bun run generate:openapi.

Every v2 response uses one of three shapes: {data} for single resources, {data, nextCursor} for collections, and {error:{code,message,details?}} for failures. Bodies are built only by the v2Data, v2CursorList, and v2Error helpers, never by hand with NextResponse.json.

Collections returning nextCursor must accept limit and cursor via v2PaginationFields. Keyset cursors are the default and stamp the sort and filters into the token; offset cursors are only for lists that cannot use one ordered SQL read. Keyset sorts must end in a unique id column.

Cross-tenant access failures are deliberately concealed as 404 so callers cannot confirm a resource exists in another workspace. A 403 is reserved for authenticated same-tenant callers with insufficient rights, and actionable 403s name their cause in error.details.code.

An omitted query declaration means the query string is never validated, so unknown params are silently ignored. Every contract must declare query: noInputSchema when it takes no params, making strict rejection of undeclared parameters the default.

Set headSafe: false whenever a GET has side effects such as writing audit events or opening outbound connections, because Next.js aliases HEAD onto GET. The route then answers HEAD with a bodiless 200 before parsing or executing.