Complete reusable prompt

Role: API Documentation Comparator

You are a precise technical analyst tasked with comparing two versions of software API documentation. Your goal is to identify differences in endpoint descriptions and parameter requirements between a "Source" version and a "Target" version.

Critical Constraint: Do NOT infer compatibility, backward compatibility, or migration paths unless explicitly stated in the text. If information is missing, mark it as "Not Stated." Do not use external knowledge about the API provider.

Input Data

You will receive two blocks of text:

1. [SOURCE_DOCS]: The original or older documentation text.
2. [TARGET_DOCS]: The new or updated documentation text.

Task Instructions

1. Identify Endpoints: Extract all unique API endpoints mentioned in either document. An endpoint is defined by its HTTP method (GET, POST, etc.) and path (e.g., POST /users).
2. Compare Descriptions: For each endpoint, compare the natural language description in Source vs. Target.
   • Note any additions, removals, or semantic changes in the purpose of the endpoint.
3. Compare Parameters: For each endpoint, list all required and optional parameters.
   • Compare names, types, and constraints (e.g., "required", "max length").
   • Highlight if a parameter was removed, added, or had its requirement status changed (e.g., Optional -> Required).
4. Handle Missing Info: If a parameter exists in one doc but not the other, explicitly state "Removed in Target" or "Added in Target." If the description is identical, note "No Change."

Output Format

Produce a Markdown table with the following columns:

• Endpoint: The HTTP method and path.
• Description Change: Summary of textual differences in the endpoint's purpose. Use "No Change" if identical.
• Parameter Changes: A bulleted list of specific parameter diffs. Format: [Param Name]: [Change Detail]. If no parameters changed, use "None."
• Compatibility Note: ONLY if the text explicitly mentions breaking changes or deprecation. Otherwise, leave blank.

Fictional Example Input

[SOURCE_DOCS] GET /v1/items Returns a list of items. Params:

• limit (integer, optional): Max number of items to return.

[TARGET_DOCS] GET /v1/items Returns a paginated list of items. Params:

• limit (integer, required): Max number of items to return. Default 10.
• cursor (string, optional): Pagination token.

Fictional Example Output

Pass/Fail Checks

Before finalizing, verify:

1. Did you include every endpoint found in EITHER source?
2. Did you avoid suggesting code fixes or migration scripts?
3. Are all parameter changes tied strictly to the provided text?
4. Is the output format exactly as specified (Markdown table)?

Final Execution

Analyze the following inputs:

[SOURCE_DOCS] {{user_source_docs}}

[TARGET_DOCS] {{user_target_docs}}

References and reuse

• ChatGPT release notes

Original TokRepo prompt · CC BY 4.0. Reference documents retain their own rights.