API Deprecation Timeline Enforcement Prompt

API governance teams use this prompt when they need to verify that every deprecated endpoint in their inventory complies with the organization's deprecation policy before a removal deadline. The job-to-be-done is a structured compliance audit that replaces manual checks across dozens of endpoints, multiple gateway configurations, and scattered documentation. The ideal user is a platform engineer, API product manager, or governance lead who owns the deprecation lifecycle and needs evidence that technical signals—Sunset headers, Deprecation headers, migration guide links, and removal dates—are correctly deployed and aligned with policy timelines. The required context includes a written deprecation policy (or a summary of its rules), an endpoint inventory listing deprecated endpoints and their target removal dates, and live HTTP response headers captured from those endpoints. Without all three inputs, the prompt cannot produce a reliable compliance report.

This prompt is designed for scheduled batch audits and CI pipeline integration. In a scheduled audit, a team runs the prompt weekly against a refreshed endpoint inventory and header snapshot to track compliance drift over time. In a CI pipeline, the prompt acts as a gate: when a gateway configuration change is proposed, the pipeline fetches headers from a staging environment, runs the prompt, and blocks the change if new violations appear. The prompt produces a structured report with four categories: compliant endpoints, endpoints missing Sunset headers, endpoints with overdue removal dates, and endpoints lacking migration guides. Each finding includes the endpoint path, the specific policy rule violated, the observed value, the expected value, and a severity flag. Escalation flags are raised for endpoints past their removal date that still respond successfully or that lack any deprecation signaling. The prompt does not assess the quality of migration guides or the legal sufficiency of deprecation communications—those require human review.

Do not use this prompt when the deprecation policy is unwritten or exists only as tribal knowledge. The prompt requires explicit rules to check against; without them, it will hallucinate compliance criteria. Do not use it as a replacement for legal review of customer-facing deprecation notices, sunset communications, or contractual obligations. The prompt validates technical artifacts—headers, dates, documentation links—not the legal adequacy of the messaging. Do not use it on endpoints that have already been removed from the gateway; the prompt needs live response headers to function. For endpoints that are already decommissioned, use a separate inventory reconciliation prompt that cross-references the gateway configuration against the deprecation register. Finally, do not treat the prompt's output as an automated enforcement action. The compliance report should feed into a human-reviewed remediation workflow, especially for escalation flags that may require customer communication or extended migration windows.

The prompt below is designed to be copied directly into your AI harness or orchestration layer. It expects you to supply your organization's deprecation policy, an inventory of endpoints with their current deprecation state, and the required output schema. Every placeholder is enclosed in square brackets—replace each one with concrete data before sending the prompt to the model. Do not leave any placeholder unresolved in production; missing policy data will cause the model to hallucinate compliance rules, and missing endpoint inventory will produce an empty or misleading report.

textCopy
You are an API governance auditor. Your task is to evaluate a set of API endpoints against a defined deprecation policy and produce a compliance report.

## DEPRECATION POLICY
[DEPRECATION_POLICY]

## ENDPOINT INVENTORY
For each endpoint, provide: path, HTTP method, deprecation status (active/deprecated/sunset), deprecation announcement date, sunset date, Sunset header presence (true/false), deprecation notice in response body (true/false), migration guide URL, and current call volume.

[ENDPOINT_INVENTORY]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "report_generated": "ISO-8601 timestamp",
  "policy_version": "string identifying which policy version was used",
  "summary": {
    "total_endpoints": number,
    "compliant": number,
    "non_compliant": number,
    "overdue_sunset": number,
    "missing_sunset_header": number,
    "missing_deprecation_notice": number,
    "missing_migration_guide": number
  },
  "findings": [
    {
      "endpoint": "GET /v1/example",
      "severity": "critical|high|medium|low",
      "category": "overdue_sunset|missing_sunset_header|missing_deprecation_notice|missing_migration_guide|timeline_violation|incomplete_notice",
      "description": "Specific violation description with policy reference",
      "policy_rule": "Quote the relevant policy clause",
      "current_state": "What was observed",
      "required_state": "What the policy requires",
      "deadline": "ISO-8601 date or null",
      "days_overdue": number or null,
      "recommended_action": "Concrete remediation step"
    }
  ],
  "escalations": [
    {
      "endpoint": "GET /v1/example",
      "reason": "Why this requires immediate attention",
      "days_overdue": number,
      "affected_consumers": "Known client impact description",
      "escalation_level": "team_lead|platform_owner|vp_engineering"
    }
  ]
}

## CONSTRAINTS
- Only flag violations that are explicitly defined in the provided policy.
- If an endpoint has no deprecation status or dates, classify it as active and do not flag it unless the policy requires proactive deprecation planning.
- If the Sunset header is present but the date does not match the policy timeline, flag it as a timeline_violation.
- If a migration guide URL is provided but returns a 404 or is empty, flag it as missing_migration_guide.
- Sort findings by severity (critical first), then by days_overdue descending.
- Escalations should only be generated for critical findings or findings more than [ESCALATION_THRESHOLD_DAYS] days overdue.
- If no violations are found, return an empty findings array and an empty escalations array with compliant summary counts.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Evaluate the endpoint inventory against the policy and return only the JSON object specified in the output schema. Do not include explanations, markdown fences, or additional text.

After copying the template, focus on three adaptation steps. First, populate [DEPRECATION_POLICY] with your actual policy text—include specific timelines (e.g., "endpoints must carry a Sunset header 90 days before removal"), required header formats, and notice content rules. Second, populate [ENDPOINT_INVENTORY] with real data from your API gateway, service catalog, or CMDB. This inventory must be refreshed before each run; stale inventory produces false compliance signals. Third, set [ESCALATION_THRESHOLD_DAYS] to your organization's risk tolerance (e.g., 30 days for high-traffic endpoints, 90 days for internal tools). If you have known examples of compliant and non-compliant endpoints, add them to [FEW_SHOT_EXAMPLES] to improve classification accuracy on edge cases like partial deprecation notices or non-standard Sunset header formats.

Before deploying this prompt into an automated pipeline, validate its output against a golden dataset of at least 20 endpoints with known compliance states. Check that the model correctly distinguishes between a missing Sunset header and a Sunset header with an incorrect date, and that it does not flag active endpoints as non-compliant. If the prompt will run in a CI/CD pipeline or governance dashboard, wrap it in a harness that logs every report, diffs findings against previous runs, and routes escalations to the appropriate channel. For high-risk APIs where a missed deprecation could break paying customers, require human review of all critical-severity findings before any automated sunset enforcement action is taken.

This prompt is designed to run as a scheduled compliance check, not a one-off review. Wire it into a cron job or CI/CD pipeline that triggers weekly or per-release. The harness must supply the current date, the deprecation policy document, and a structured inventory of all published API endpoints with their deprecation metadata. The model's output is a compliance report, so the harness must validate that the report schema is intact before forwarding findings to an issue tracker or notification system.

Input assembly requires three data sources: (1) a machine-readable API inventory (OpenAPI spec, API gateway export, or service catalog) containing endpoint, deprecation_date, sunset_date, sunset_header_present, deprecation_notice_url, and migration_guide_url fields; (2) the organization's deprecation policy document specifying minimum notice periods, required headers, and documentation standards; and (3) the current date for timeline comparison. The harness should transform the API inventory into a structured JSON array and inject it into the [API_INVENTORY] placeholder. The policy document goes into [DEPRECATION_POLICY], and the current date into [CURRENT_DATE]. If the inventory is large, batch endpoints by service and run the prompt per batch, then merge results.

Output validation is critical because the compliance report drives escalation decisions. After the model responds, validate that the output is valid JSON matching the expected schema: a top-level compliance_report object with overdue_items (array), upcoming_deadlines (array), compliant_endpoints (array), and escalation_flags (array). Each item must contain endpoint, severity, policy_violation, and recommended_action fields. If validation fails, retry once with the validation error injected into the [PREVIOUS_ERRORS] placeholder. If the second attempt also fails, log the raw output and alert the API governance team for manual review. Do not silently accept malformed reports.

Escalation routing should be automated based on the severity field in the output. Overdue items with severity: critical (endpoints past their sunset date with no migration guide) should create P0 tickets in the API team's issue tracker. Items with severity: high (sunset date within 30 days with missing Sunset headers) should create P1 tickets. The harness should deduplicate against open tickets to avoid flooding the team with repeat alerts. For each escalation, include the raw compliance report as evidence and a link to the specific policy clause violated.

Model choice and latency are straightforward for this workflow. Use a model with strong JSON mode and instruction-following, such as GPT-4o or Claude 3.5 Sonnet. This is a batch governance task, not a real-time user-facing feature, so latency under 30 seconds is acceptable. Enable structured output mode if the model provider supports it, and set temperature=0 for deterministic compliance rulings. If the API inventory exceeds the model's context window, pre-filter to only deprecated or sunset-eligible endpoints before invoking the prompt, since compliant active endpoints need minimal review.

Logging and audit trail requirements are high because deprecation compliance failures can cause production incidents. Log every prompt invocation with a unique run_id, the input inventory hash, the policy version, the raw model output, the validation result, and any escalation actions taken. Store these logs in an append-only audit store for at least the duration of the longest deprecation window. This ensures that when a client reports a surprise breaking change, the governance team can trace whether the compliance check ran, what it found, and what action was taken. Never run this prompt without audit logging enabled.