OpenAPI Pagination Parameter Standardization Prompt Template

API platforms with more than a handful of list endpoints inevitably drift. One team uses offset and limit, another uses page and per_page, and a third rolls a custom cursor implementation with no Link header documentation. This prompt takes a raw OpenAPI specification and enforces a single, organization-wide pagination contract across every collection endpoint. It produces standardized parameter definitions, response header documentation, and a compliance report that flags endpoints that need manual review.

Use this prompt when you are preparing a spec for public documentation, generating SDKs, or running a governance review before a version freeze. The prompt assumes you have already chosen a pagination strategy—cursor-based, offset-based, or page-based—and that the input spec is structurally valid OpenAPI 3.0 or 3.1. Do not use this prompt to design your pagination strategy from scratch; it enforces a decision, it does not make one. Also avoid using it on specs that mix pagination styles intentionally across different resource types unless you provide explicit per-resource overrides in the [CONSTRAINTS] block.

Before running this prompt, confirm that every collection endpoint in your spec is identifiable. The prompt relies on operation ID conventions, path patterns, or response schema hints to detect list endpoints. If your spec uses inconsistent naming or lacks response array indicators, add a pre-processing step to tag collection endpoints or provide a list of operation IDs in [CONTEXT]. After the prompt runs, review the compliance report carefully. Endpoints flagged for manual review often involve streaming responses, nested pagination, or legacy cursor formats that require human judgment. Wire the output into your CI pipeline so every spec change is checked against the pagination standard before merge.

This prompt template is designed to be pasted directly into your AI workflow. It instructs the model to analyze an OpenAPI specification and enforce a consistent pagination strategy across all list endpoints. The template uses square-bracket placeholders—such as [OPENAPI_SPEC], [PAGINATION_STYLE], and [OUTPUT_SCHEMA]—which you must replace with your actual values before execution. The prompt is self-contained and can be used independently of the rest of this playbook.

textCopy
You are an API design expert enforcing strict pagination standards.

Analyze the provided OpenAPI specification and standardize pagination parameters for every endpoint that returns a list of resources.

[OPENAPI_SPEC]

[PAGINATION_STYLE]

For each list endpoint, perform the following actions:
1.  If the endpoint does not have pagination parameters, add them according to the [PAGINATION_STYLE].
2.  If the endpoint has pagination parameters that do not match the [PAGINATION_STYLE], refactor them to match.
3.  Ensure the response schema for a paginated list includes a wrapper object with fields for the array of items and pagination metadata (e.g., `next_cursor`, `total_count`).
4.  Document the use of `Link` headers for pagination in the endpoint's description and response headers, following RFC 5988.

Return the complete, modified OpenAPI specification in valid YAML format. Do not include any conversational text outside the YAML document.

[OUTPUT_SCHEMA]

[CONSTRAINTS]

To adapt this template, replace the placeholders with your concrete data. [OPENAPI_SPEC] should contain the raw YAML or JSON of your specification. [PAGINATION_STYLE] should be a clear instruction, such as 'Use cursor-based pagination with cursor and limit query parameters.' [OUTPUT_SCHEMA] can be used to specify the exact structure of the pagination wrapper object. [CONSTRAINTS] is the place to add rules like 'Do not change any endpoint paths or HTTP methods' or 'Preserve all existing text in the description fields.' For high-risk or regulated APIs, always follow this automated step with a manual review of the generated specification to ensure no business logic was altered.

This prompt is designed to be a deterministic step inside an automated API governance pipeline, not a one-off chat interaction. The primary integration point is a CI/CD check that runs on every pull request touching an OpenAPI specification file. When a new or modified spec is detected, the pipeline extracts all operations tagged as list endpoints (typically GET operations on collection paths) and invokes this prompt for each one that lacks standardized pagination parameters. The prompt's output is a JSON patch or a complete parameter array that can be programmatically merged back into the spec file. The harness should treat the model's output as a proposal that requires structural validation before acceptance, never as an automatic overwrite of the source spec.

The implementation harness must enforce several hard constraints before and after the model call. Pre-flight checks should verify that the input spec fragment is valid OpenAPI, that the target operation is indeed a collection endpoint (by checking for an array response schema or a list operationId suffix), and that the existing parameters do not already contain a complete pagination set. Post-generation validation must confirm that every returned parameter object includes the required OpenAPI fields (name, in, required, schema), that the pagination style is consistent with a declared global standard (e.g., cursor, offset, or page), and that Link header documentation is present in the response headers when cursor-based pagination is selected. A structural diff against the original spec fragment should be logged so reviewers can see exactly what the prompt added. If the model proposes a pagination style that conflicts with the organization's registered standard in an API catalog, the harness must flag it for human review rather than silently applying it.

For model selection, use a model with strong JSON schema adherence and low creative variance, such as gpt-4o or claude-3-5-sonnet with response_format set to json_object and a temperature of 0. Avoid models prone to hallucinating parameter names or inventing non-standard pagination headers. The prompt should be called with a strict output schema that matches the expected parameter array structure. Retry logic should be minimal: if the output fails JSON Schema validation, retry once with the validation error injected into the prompt as a correction hint. If the second attempt also fails, surface the failure to the PR author with the raw output and the specific schema violations. Do not loop indefinitely. Logging must capture the input operation ID, the model used, the generated parameters, the validation result, and whether the change was auto-applied or queued for review. This audit trail is essential for governance reviews and for debugging cases where the prompt proposes an unexpected pagination style.

Human review gates are required when the prompt proposes a pagination style change for an endpoint that already has pagination parameters (a migration scenario), when the generated parameters include a style or explode value that differs from the organization's baseline, or when the endpoint's response schema is too ambiguous for the model to confidently determine whether it returns a collection. In these cases, the harness should post a comment on the PR with the proposed changes and a structured summary of what the model changed and why, then block merge until a designated API designer approves. For endpoints that are net-new and match a clear collection pattern, auto-application is acceptable provided the post-generation structural checks pass. Next step: integrate this harness into your OpenAPI linting stage (e.g., as a custom Spectral rule or a GitHub Actions step) and register your organization's pagination standard as a configuration input so the prompt always proposes the correct style.