feat(manage-api): add x-speakeasy-pagination extension to all paginated list endpoints (#1300)

* feat(manage-api): add x-speakeasy-pagination extension to all paginated list endpoints

Adds native Speakeasy pagination support to 17 list endpoints by adding
the x-speakeasy-pagination OpenAPI extension. This will enable the
generated SDK to have built-in pagination methods like .next().

- Created shared.ts with reusable speakeasyOffsetLimitPagination constant
- Updated all paginated route files to use the shared constant

* biome format and pagination improvements

Author: amikofalvy

.changeset/olympic-red-leopard.md

@@ -0,0 +1,12 @@
+---
+"@inkeep/agents-cli": patch
+"@inkeep/agents-core": patch
+"@inkeep/agents-manage-api": patch
+"@inkeep/agents-manage-ui": patch
+"@inkeep/agents-run-api": patch
+"@inkeep/agents-sdk": patch
+"@inkeep/create-agents": patch
+"@inkeep/ai-sdk-provider": patch
+---
+
+Add x-speakeasy-pagination extension to all paginated list endpoints for Speakeasy SDK native pagination support

agents-docs/src/app/layout.tsx

@@ -116,40 +116,40 @@ export default function Layout({ children }: LayoutProps<'/'>) {
           <PostHogPageview />
         </Suspense>
         <PostHogProvider>
-        <RootProvider search={{ SearchDialog }}>
-          <DocsLayout
-            tree={source.pageTree}
-            nav={{
-              title: <Logo className="!w-[110px] !h-[32px]" />,
-            }}
-            sidebar={{
-              className: 'bg-background',
-              banner: (
-                <div className="flex gap-2">
-                  <Button
-                    variant="outline"
-                    size="sm"
-                    className="grow text-primary border-primary/30 hover:bg-primary/5 dark:bg-primary/5 hover:text-primary dark:text-primary dark:border-primary/30 dark:hover:bg-primary/10"
-                    asChild
-                  >
-                    <a
-                      href="https://inkeep.com/cloud-waitlist?cta_id=docs_nav"
-                      target="_blank"
-                      rel="noreferrer"
+          <RootProvider search={{ SearchDialog }}>
+            <DocsLayout
+              tree={source.pageTree}
+              nav={{
+                title: <Logo className="!w-[110px] !h-[32px]" />,
+              }}
+              sidebar={{
+                className: 'bg-background',
+                banner: (
+                  <div className="flex gap-2">
+                    <Button
+                      variant="outline"
+                      size="sm"
+                      className="grow text-primary border-primary/30 hover:bg-primary/5 dark:bg-primary/5 hover:text-primary dark:text-primary dark:border-primary/30 dark:hover:bg-primary/10"
+                      asChild
                     >
-                      <Cloud />
-                      Inkeep Cloud
-                    </a>
-                  </Button>
-                  <GithubStars />
-                </div>
-              ),
-            }}
-            links={linkItems}
-          >
-            {children}
-          </DocsLayout>
-        </RootProvider>
+                      <a
+                        href="https://inkeep.com/cloud-waitlist?cta_id=docs_nav"
+                        target="_blank"
+                        rel="noreferrer"
+                      >
+                        <Cloud />
+                        Inkeep Cloud
+                      </a>
+                    </Button>
+                    <GithubStars />
+                  </div>
+                ),
+              }}
+              links={linkItems}
+            >
+              {children}
+            </DocsLayout>
+          </RootProvider>
         </PostHogProvider>
       </body>
     </html>

agents-docs/src/app/posthog-pageview.tsx

@@ -1,8 +1,8 @@
-"use client";
+'use client';
 
-import { usePathname, useSearchParams } from "next/navigation";
-import { useEffect } from "react";
-import posthog from "posthog-js";
+import { usePathname, useSearchParams } from 'next/navigation';
+import posthog from 'posthog-js';
+import { useEffect } from 'react';
 
 export default function PostHogPageview() {
   const pathname = usePathname();
@@ -17,17 +17,15 @@ export default function PostHogPageview() {
 
       posthog.register_once({
         initial_referrer:
-          typeof window !== "undefined"
-            ? document.referrer || "(direct)"
-            : "(direct)",
+          typeof window !== 'undefined' ? document.referrer || '(direct)' : '(direct)',
         initial_landing_page: pathname,
       });
 
-      const utmSource = searchParams?.get("utm_source");
-      const utmMedium = searchParams?.get("utm_medium");
-      const utmCampaign = searchParams?.get("utm_campaign");
-      const utmContent = searchParams?.get("utm_content");
-      const utmTerm = searchParams?.get("utm_term");
+      const utmSource = searchParams?.get('utm_source');
+      const utmMedium = searchParams?.get('utm_medium');
+      const utmCampaign = searchParams?.get('utm_campaign');
+      const utmContent = searchParams?.get('utm_content');
+      const utmTerm = searchParams?.get('utm_term');
 
       if (utmSource || utmMedium || utmCampaign || utmContent || utmTerm) {
         const utmParams: Record<string, string> = {};
@@ -41,11 +39,11 @@ export default function PostHogPageview() {
       }
 
       const clickIdParams: Record<string, string> = {};
-      const gclid = searchParams?.get("gclid");
-      const fbclid = searchParams?.get("fbclid");
-      const msclkid = searchParams?.get("msclkid");
-      const li_fat_id = searchParams?.get("li_fat_id");
-      const ttclid = searchParams?.get("ttclid");
+      const gclid = searchParams?.get('gclid');
+      const fbclid = searchParams?.get('fbclid');
+      const msclkid = searchParams?.get('msclkid');
+      const li_fat_id = searchParams?.get('li_fat_id');
+      const ttclid = searchParams?.get('ttclid');
 
       if (gclid) clickIdParams.gclid = gclid;
       if (fbclid) clickIdParams.fbclid = fbclid;
@@ -57,11 +55,11 @@ export default function PostHogPageview() {
         posthog.register_once(clickIdParams);
       }
 
-      posthog.capture("$pageview", {
+      posthog.capture('$pageview', {
         $current_url: url,
       });
     }
   }, [pathname, searchParams]);
 
   return null;
-}
+}

agents-docs/src/instrumentation-client.ts

@@ -1,33 +1,32 @@
-"use client";
+'use client';
 
-import posthog from "posthog-js";
+import posthog from 'posthog-js';
 
-if (typeof window !== "undefined") {
-  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY || "", {
-    api_host:
-      process.env.NEXT_PUBLIC_POSTHOG_HOST || "https://us.i.posthog.com",
+if (typeof window !== 'undefined') {
+  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY || '', {
+    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
     capture_pageview: false,
-    person_profiles: "always",
+    person_profiles: 'always',
     disable_surveys: true,
     disable_external_dependency_loading: true,
     loaded: (posthog) => {
       posthog.register({
-        site: "agents-docs",
+        site: 'agents-docs',
       });
 
-      if (process.env.NODE_ENV === "development") {
-        console.log("[PostHog] Initialized successfully");
+      if (process.env.NODE_ENV === 'development') {
+        console.log('[PostHog] Initialized successfully');
       }
     },
     session_recording: {
       maskAllInputs: true,
       maskTextFn: (text, element) => {
-        if (element?.dataset.demo === "true") {
+        if (element?.dataset.demo === 'true') {
           return text;
         }
-        return "*".repeat(text.length);
+        return '*'.repeat(text.length);
       },
-      maskTextSelector: "*",
+      maskTextSelector: '*',
     },
   });
-}
+}

agents-docs/src/lib/analytics/posthog-events.ts

@@ -1,8 +1,8 @@
-export const DOCS_PAGE_VIEWED = "docs_page_viewed";
-export const DOCS_LINK_CLICKED = "docs_link_clicked";
-export const DOCS_SEARCH_PERFORMED = "docs_search_performed";
-export const DOCS_CODE_COPIED = "docs_code_copied";
-export const DOCS_EXTERNAL_LINK_CLICKED = "docs_external_link_clicked";
-export const DOCS_GITHUB_LINK_CLICKED = "docs_github_link_clicked";
-export const DOCS_SLACK_LINK_CLICKED = "docs_slack_link_clicked";
-export const DOCS_CTA_CLICKED = "docs_cta_clicked";
+export const DOCS_PAGE_VIEWED = 'docs_page_viewed';
+export const DOCS_LINK_CLICKED = 'docs_link_clicked';
+export const DOCS_SEARCH_PERFORMED = 'docs_search_performed';
+export const DOCS_CODE_COPIED = 'docs_code_copied';
+export const DOCS_EXTERNAL_LINK_CLICKED = 'docs_external_link_clicked';
+export const DOCS_GITHUB_LINK_CLICKED = 'docs_github_link_clicked';
+export const DOCS_SLACK_LINK_CLICKED = 'docs_slack_link_clicked';
+export const DOCS_CTA_CLICKED = 'docs_cta_clicked';

agents-docs/src/lib/analytics/posthog-provider.tsx

@@ -1,10 +1,10 @@
-"use client";
+'use client';
 
-import { PostHogProvider as PHProvider } from "posthog-js/react";
-import posthog from "posthog-js";
-import type { ReactNode } from "react";
-import "@/instrumentation-client";
+import posthog from 'posthog-js';
+import { PostHogProvider as PHProvider } from 'posthog-js/react';
+import type { ReactNode } from 'react';
+import '@/instrumentation-client';
 
 export function PostHogProvider({ children }: { children: ReactNode }) {
   return <PHProvider client={posthog}>{children}</PHProvider>;
-}
+}

agents-docs/src/lib/analytics/posthog-server.ts

@@ -1,24 +1,18 @@
-import { PostHog } from "posthog-node";
+import { PostHog } from 'posthog-node';
 
 export async function captureServerEvent(
   distinctId: string,
   event: string,
   properties?: Record<string, unknown>
 ): Promise<void> {
-  if (
-    process.env.NODE_ENV === "test" ||
-    !process.env.NEXT_PUBLIC_POSTHOG_KEY
-  ) {
-    console.log(
-      `[PostHog Server] Skipping event capture: ${event} (${distinctId})`
-    );
+  if (process.env.NODE_ENV === 'test' || !process.env.NEXT_PUBLIC_POSTHOG_KEY) {
+    console.log(`[PostHog Server] Skipping event capture: ${event} (${distinctId})`);
     return;
   }
 
   try {
     const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY, {
-      host:
-        process.env.NEXT_PUBLIC_POSTHOG_HOST || "https://us.i.posthog.com",
+      host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
       flushAt: 1,
       flushInterval: 0,
     });
@@ -28,8 +22,8 @@ export async function captureServerEvent(
       event,
       properties: {
         ...properties,
-        $lib: "posthog-node",
-        source: "server",
+        $lib: 'posthog-node',
+        source: 'server',
       },
     });
 
@@ -40,28 +34,22 @@ export async function captureServerEvent(
       properties,
     });
   } catch (error) {
-    console.error("[PostHog Server] Failed to capture event:", error);
+    console.error('[PostHog Server] Failed to capture event:', error);
   }
 }
 
 export async function identifyServerUser(
   distinctId: string,
   properties?: Record<string, unknown>
 ): Promise<void> {
-  if (
-    process.env.NODE_ENV === "test" ||
-    !process.env.NEXT_PUBLIC_POSTHOG_KEY
-  ) {
-    console.log(
-      `[PostHog Server] Skipping user identify: ${distinctId}`
-    );
+  if (process.env.NODE_ENV === 'test' || !process.env.NEXT_PUBLIC_POSTHOG_KEY) {
+    console.log(`[PostHog Server] Skipping user identify: ${distinctId}`);
     return;
   }
 
   try {
     const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY, {
-      host:
-        process.env.NEXT_PUBLIC_POSTHOG_HOST || "https://us.i.posthog.com",
+      host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
       flushAt: 1,
       flushInterval: 0,
     });
@@ -77,6 +65,6 @@ export async function identifyServerUser(
       properties,
     });
   } catch (error) {
-    console.error("[PostHog Server] Failed to identify user:", error);
+    console.error('[PostHog Server] Failed to identify user:', error);
   }
-}
+}

agents-manage-api/src/routes/agent.ts

@@ -14,7 +14,7 @@ import {
   getAgentById,
   getAgentSubAgentInfos,
   getFullAgentDefinition,
-  listAgents,
+  listAgentsPaginated,
   PaginationQueryParamsSchema,
   RelatedAgentInfoListResponse,
   TenantProjectAgentParamsSchema,
@@ -26,6 +26,7 @@ import {
 import dbClient from '../data/db/dbClient';
 import { requirePermission } from '../middleware/require-permission';
 import type { BaseAppVariables } from '../types/app';
+import { speakeasyOffsetLimitPagination } from './shared';
 
 const app = new OpenAPIHono<{ Variables: BaseAppVariables }>();
 
@@ -68,22 +69,18 @@ app.openapi(
       },
       ...commonGetErrorResponses,
     },
+    ...speakeasyOffsetLimitPagination,
   }),
   async (c) => {
     const { tenantId, projectId } = c.req.valid('param');
     const page = Number(c.req.query('page')) || 1;
     const limit = Math.min(Number(c.req.query('limit')) || 10, 100);
 
-    const agent = await listAgents(dbClient)({ scopes: { tenantId, projectId } });
-    return c.json({
-      data: agent,
-      pagination: {
-        page,
-        limit,
-        total: agent.length,
-        pages: Math.ceil(agent.length / limit),
-      },
+    const result = await listAgentsPaginated(dbClient)({
+      scopes: { tenantId, projectId },
+      pagination: { page, limit },
     });
+    return c.json(result);
   }
 );
 

agents-manage-api/src/routes/agentToolRelations.ts

@@ -23,6 +23,7 @@ import {
 import dbClient from '../data/db/dbClient';
 import { requirePermission } from '../middleware/require-permission';
 import type { BaseAppVariables } from '../types/app';
+import { speakeasyOffsetLimitPagination } from './shared';
 
 const app = new OpenAPIHono<{ Variables: BaseAppVariables }>();
 
@@ -68,6 +69,7 @@ app.openapi(
       },
       ...commonGetErrorResponses,
     },
+    ...speakeasyOffsetLimitPagination,
   }),
   async (c) => {
     const { tenantId, projectId, agentId } = c.req.valid('param');

agents-manage-api/src/routes/apiKeys.ts

@@ -21,6 +21,7 @@ import {
 import dbClient from '../data/db/dbClient';
 import { requirePermission } from '../middleware/require-permission';
 import type { BaseAppVariables } from '../types/app';
+import { speakeasyOffsetLimitPagination } from './shared';
 
 const app = new OpenAPIHono<{ Variables: BaseAppVariables }>();
 
@@ -67,6 +68,7 @@ app.openapi(
       },
       ...commonGetErrorResponses,
     },
+    ...speakeasyOffsetLimitPagination,
   }),
   async (c) => {
     const { tenantId, projectId } = c.req.valid('param');