Pagination and Filtering Parameter Documentation Prompt Template

This prompt is built for API designers and technical writers who need to produce a single, authoritative reference for pagination, sorting, and filtering parameters across a multi-endpoint API surface. The core job-to-be-done is consistency enforcement: taking an OpenAPI specification or a set of endpoint definitions and generating a unified parameter reference that eliminates naming drift, documents cursor vs offset patterns, enumerates filter operators, and validates that every paginated endpoint follows the same contract. Use this prompt when you are standardizing a sprawling API, onboarding new endpoints into an existing pagination convention, or auditing documentation for gaps where some endpoints silently deviate from the team's agreed patterns.

The prompt requires structured input: an OpenAPI spec file, a collection of endpoint definitions, or a documented API contract. It works best when the input already contains the raw parameter definitions, and the model's job is to normalize, cross-reference, and flag inconsistencies. Do not use this prompt for designing the pagination mechanism itself, generating implementation code, or documenting non-REST transport protocols without significant adaptation. It is a documentation standardization tool, not a backend design assistant. For high-risk APIs where pagination bugs could cause data loss or billing errors, always pair the generated reference with a human review step that verifies cursor stability, default page sizes, and maximum limit enforcement against the actual implementation.

Before running this prompt, gather the complete API contract and identify the specific pagination convention your team has adopted—whether it is cursor-based, offset-based, page-based, or a hybrid. If your team has not yet agreed on a convention, resolve that design decision first; this prompt documents and validates an existing standard, it does not create one. After generating the reference, use the built-in consistency checks to flag endpoints that are missing pagination parameters, using inconsistent parameter names, or lacking documented filter operators. The output should feed directly into your API reference portal or developer docs, with a clear changelog noting any breaking changes to parameter names or default values.

This prompt template generates standardized parameter tables for pagination, sorting, and filtering from your API specification. It enforces consistency across endpoints by requiring explicit cursor vs. offset patterns, filter operator definitions, sort field enumeration, and default page sizes. The output is designed to be directly embedded into API reference pages, with field-level detail that helps integrators understand pagination mechanics without reading implementation code.

textCopy
You are an API documentation engineer. Generate a complete pagination, sorting, and filtering parameter reference for the endpoint described below.

[API_SPECIFICATION]

Generate documentation that covers:

1. **Pagination Parameters**
   - Pagination method: cursor-based, offset-based, or page-based
   - Parameter names, types, required/optional status, default values, and maximum limits
   - For cursor-based: next_cursor/prev_cursor semantics, cursor encoding, and cursor expiration behavior
   - For offset-based: offset and limit parameters, maximum limit, and total count availability
   - Response metadata fields: next_cursor, has_more, total_count, or equivalent

2. **Sorting Parameters**
   - Parameter name and format (e.g., sort_by, sort_order, order_by)
   - Complete enumeration of sortable fields from the endpoint's response schema
   - Sort direction syntax: ascending/descending conventions (asc/desc, +/- prefix, or separate order parameter)
   - Default sort order when no parameter is provided
   - Multi-field sort support and precedence rules

3. **Filtering Parameters**
   - For each filterable field: parameter name, type, supported operators, and multi-value support
   - Operator syntax: equals, not_equals, greater_than, less_than, contains, starts_with, in, between, is_null
   - Date/time filter formats and timezone handling
   - Enum field filter values with complete value lists
   - Boolean field filter conventions
   - Nested or relationship-based filter syntax if applicable
   - Combining multiple filters: AND/OR semantics and precedence

4. **Consistency Validation**
   - Flag any pagination parameter names that differ from other endpoints in the same API
   - Flag any sort field names that don't match response schema property names
   - Flag any filter operators that deviate from the API-wide filter convention
   - Flag any missing default values or undocumented maximum limits

[OUTPUT_SCHEMA]
{
  "endpoint": "string (HTTP method and path)",
  "pagination": {
    "method": "cursor | offset | page",
    "parameters": [
      {
        "name": "string",
        "type": "string",
        "required": boolean,
        "default": "string or null",
        "max_value": "number or null",
        "description": "string"
      }
    ],
    "response_metadata_fields": [
      {
        "name": "string",
        "type": "string",
        "description": "string"
      }
    ],
    "notes": "string (cursor encoding, expiration, or edge cases)"
  },
  "sorting": {
    "parameter_name": "string",
    "sortable_fields": [
      {
        "field": "string (must match response schema)",
        "type": "string",
        "description": "string"
      }
    ],
    "direction_syntax": "string (e.g., 'asc/desc', '+/- prefix')",
    "default_sort": "string",
    "multi_field_sort_supported": boolean,
    "notes": "string"
  },
  "filtering": {
    "parameters": [
      {
        "name": "string",
        "type": "string",
        "operators": ["string (e.g., eq, neq, gt, lt, contains, in, between)"],
        "multi_value_supported": boolean,
        "description": "string",
        "enum_values": ["string or null"]
      }
    ],
    "combination_logic": "string (AND/OR semantics)",
    "notes": "string (date formats, timezone handling, special cases)"
  },
  "consistency_flags": [
    {
      "severity": "warning | error",
      "field": "string",
      "issue": "string",
      "recommendation": "string"
    }
  ]
}

[CONSTRAINTS]
- Every sortable field name must exactly match a property name in the endpoint's response schema.
- Every filterable field must reference an existing response schema property or queryable field.
- Pagination parameter names must match the convention used by other endpoints in the same API.
- Default values must be explicitly stated; do not assume defaults.
- Maximum limits must be documented; if no limit exists, state "unlimited" with a warning.
- Enum filter values must list every valid value from the specification.
- If the specification is incomplete for any required field, flag it in consistency_flags rather than guessing.

To adapt this prompt, replace [API_SPECIFICATION] with your OpenAPI spec fragment, endpoint definition, or implementation code. Adjust [OUTPUT_SCHEMA] if your documentation system expects a different JSON structure. The [CONSTRAINTS] section enforces consistency rules; modify these to match your API's specific pagination conventions, such as requiring page_token instead of cursor or enforcing RFC 3339 date formats. For APIs with custom filter DSLs, add operator syntax rules to the constraints. Always run the output through a schema validator before publishing to catch hallucinated field names or missing required properties.

This prompt is designed to run as a batch documentation generation step inside a CI/CD pipeline or a scheduled doc refresh job. The typical trigger is a change to the OpenAPI specification file, a source annotation update, or a manual invocation via a docs platform CLI. The harness should extract the relevant endpoint definitions, pagination parameters, and filter schemas from the spec or codebase, then feed them into the prompt as structured [INPUT] blocks. Do not run this prompt on every commit to unrelated code paths; scope the trigger to paths affecting API contracts, query parameter definitions, or schema files that define pagination and filtering models.

Pipeline wiring: The harness should parse the OpenAPI spec (or equivalent source) to isolate all paginated endpoints. For each endpoint, construct a prompt call with: [ENDPOINT_PATH], [PAGINATION_STRATEGY] (cursor, offset, page-based, or keyset), [PAGE_SIZE_DEFAULT], [MAX_PAGE_SIZE], [SORT_FIELDS] with allowed directions, [FILTER_PARAMETERS] with operators and types, and [RESPONSE_SCHEMA] for the paginated envelope. The model should return structured output conforming to [OUTPUT_SCHEMA]—a JSON object with parameter_table, pagination_behavior, filtering_rules, sort_options, and examples. Validate the output immediately: check that every parameter in the spec appears in the documentation, that default values match, that enum values for sort directions are correct, and that example requests use valid filter operators. If validation fails, retry once with the validation errors injected into [CONSTRAINTS]. If the retry also fails, flag the endpoint for human review and block the doc merge.

Model choice and cost: Use a model with strong schema-following capability (GPT-4o, Claude 3.5 Sonnet, or equivalent) for the initial generation pass. For subsequent consistency-check runs where only diffs are evaluated, a smaller model may suffice. Cache the prompt prefix containing the style guide and output schema instructions to reduce token costs across hundreds of endpoints. Logging and audit: Log every generation with the prompt version, spec commit SHA, model used, validation results, and any human review flags. Store outputs in a review branch of the docs repository, not directly in production. Require a human approval step for any endpoint where the generated documentation changes an existing pagination parameter description, removes a documented filter, or alters default values. This prevents documentation regressions from automated runs. Failure modes to monitor: The most common production failures are (1) the model inventing filter operators not present in the spec, (2) omitting newly added pagination parameters, (3) misdocumenting cursor formats for keyset pagination, and (4) generating example requests that use incompatible filter combinations. Your eval suite should include test cases for each of these failure modes, and your harness should block merges when any eval case fails.