docs(api): define v2 list and lookup contracts (#3169)

* docs(api): define v2 list and lookup contracts

* docs(api): deprecate legacy v2 paginator

Author: wklken

src/dashboard/apigateway/apigateway/apis/AGENTS.md

@@ -45,6 +45,25 @@ Open and v2 automation surfaces use the normalized stored protocol instead.
 Masked-secret restoration is a Web update-boundary behavior; do not apply it to
 Open or Sync input, where submitted stored-protocol values are literal.
 
+## V2 List And Lookup Contracts
+
+- Keep collection listing and exact batch lookup as separate APIs under
+  `apis.v2`. A list API serves discovery and filtering on the collection route;
+  when callers need exact batch retrieval by identifiers such as `ids` or
+  `names`, add a non-paginated `-/lookup/` route that returns `data: [...]`.
+  Do not add an identifier-list mode to a list API that changes its normal
+  visibility, filtering, or pagination semantics.
+- List APIs use the standard `limit`/`offset` pagination contract and return
+  `data: {"count": <int>, "results": [...]}`.
+- `apigateway.utils.paginator.LimitOffsetPaginator` is deprecated for
+  `apis.v2`; do not use it in new or modified v2 endpoints. Use the configured
+  `apigateway.common.pagination.StandardLimitOffsetPagination` (or a
+  surface-specific subclass) through `self.paginate_queryset(...)` and
+  `self.get_paginated_response(...)` instead. Do not hand-build the envelope
+  when the view owns an unpaginated queryset or list. When a downstream source
+  already applies `limit`/`offset` and supplies the total count, preserve the
+  same standard response envelope without paginating the page again.
+
 ## OpenAPI Contract
 
 When changing an open API, keep these representations aligned: