Deprecation Notice Extraction Prompt for API Changelogs

This prompt is designed for tool platform operators and API governance engineers who need to convert unstructured changelogs, release notes, and developer blog posts into a structured, machine-readable registry of deprecation events. It extracts affected endpoints, sunset dates, migration paths, and replacement guidance so that downstream systems—such as agent tool registries, CI/CD pipelines, and internal compliance dashboards—can automatically flag breaking changes before they cause production failures. Use this prompt when you have a stream of textual changelogs from multiple API providers and need a consistent, queryable deprecation record.

The ideal workflow ingests changelog text from RSS feeds, email notifications, or scraped documentation pages and passes each document through this prompt. The structured output should be validated against a known schema before insertion into a deprecation registry database. You must pair this prompt with a validation layer that checks for required fields (affected endpoint, deprecation date, replacement), rejects records with future dates that lack evidence, and flags extractions where the confidence is low or the source text is ambiguous. For high-risk APIs that power revenue-critical agent workflows, route low-confidence extractions to a human review queue before the deprecation record becomes actionable in downstream systems.

Do not use this prompt for real-time HTTP header parsing, runtime version negotiation, or generating migration code; those tasks require separate, specialized prompts such as the API Deprecation Header Parsing Prompt or the Agent Adaptation Prompt for Deprecated Tool Endpoints. This prompt also assumes the input is a natural language changelog—it will perform poorly on raw diff outputs, structured OpenAPI changelogs, or machine-generated commit messages without narrative context. If your input source is a structured API specification, use a schema diffing approach instead.

This prompt template is designed to be pasted directly into your application code. It instructs the model to parse raw changelog text and return a structured JSON array of deprecation notices. Each notice includes the affected endpoint, deprecation date, sunset date, migration target, and any guidance provided. The template uses square-bracket placeholders that you must replace with actual values at runtime before sending the request to the model.

textCopy
You are an API deprecation analyst. Your task is to extract structured deprecation records from the provided changelog text.

## Input
[CHANGELOG_TEXT]

## Output Schema
Return a JSON object with a single key "deprecations" containing an array of objects. Each object must have the following fields:
- "affected_endpoint": string (the HTTP method and path, e.g., "GET /v1/users")
- "deprecation_date": string or null (ISO 8601 date when the deprecation was announced)
- "sunset_date": string or null (ISO 8601 date when the endpoint will be removed)
- "migration_target": string or null (the recommended replacement endpoint or feature)
- "guidance": string or null (any migration instructions or notes provided)
- "confidence": number between 0.0 and 1.0 (your confidence that this is a real deprecation)

## Constraints
- Only extract deprecations that are explicitly stated. Do not infer deprecations from general product announcements.
- If a date is mentioned as a quarter (e.g., "Q3 2025"), convert it to the first day of that quarter (e.g., "2025-07-01").
- If no sunset date is provided, set "sunset_date" to null.
- If multiple endpoints are deprecated in a single notice, create a separate record for each endpoint.
- Set "confidence" to 1.0 only if the text uses explicit deprecation language ("deprecated", "will be removed", "sunset"). Use 0.8 if the language is suggestive but not explicit ("legacy", "no longer recommended").

## Examples
Input: "The /v1/orders endpoint is deprecated effective 2024-01-15 and will be removed on 2024-07-15. Please migrate to /v2/orders."
Output: {"deprecations": [{"affected_endpoint": "GET /v1/orders", "deprecation_date": "2024-01-15", "sunset_date": "2024-07-15", "migration_target": "/v2/orders", "guidance": "Please migrate to /v2/orders.", "confidence": 1.0}]}

Input: "We've launched a new analytics dashboard. The old reports page is still available but we recommend switching."
Output: {"deprecations": []}

## Risk Level
[RISK_LEVEL]

If RISK_LEVEL is "high", you must include a "requires_human_review" boolean field in each record. Set it to true if any of the following apply:
- The sunset_date is within 30 days of today.
- The migration_target is null or ambiguous.
- The guidance field contains conditional language ("may", "might", "could").

To adapt this prompt for your environment, replace [CHANGELOG_TEXT] with the raw markdown or plain text of the changelog. Set [RISK_LEVEL] to "high" if you are processing changelogs for production-critical APIs where a missed deprecation could cause an outage; otherwise set it to "standard". The output schema is designed to be ingested directly by a monitoring system or a tool registry. If your internal tool catalog uses different field names, adjust the schema accordingly, but keep the field descriptions intact so the model understands the semantic mapping. Always validate the JSON output against the schema before persisting it, and log any records with confidence below 0.9 for manual review.

This prompt is designed to be called as part of a scheduled or event-driven ingestion pipeline that processes unstructured API changelogs into structured deprecation records. The typical integration pattern is: fetch raw changelog content from a source (RSS feed, GitHub releases, documentation scraper, or internal CMS), chunk the content by release or date range, and invoke the prompt for each chunk. The output should be validated against the expected schema before being written to a deprecation registry, notification system, or agent tool-awareness database. Do not treat this as a one-shot prompt for an entire multi-year changelog; chunking by release boundary is essential for recall and grounding.

Validation is the most critical harness component. The prompt produces JSON with fields like affected_endpoints, deprecation_date, sunset_date, migration_guidance, and breaking_change. Before ingestion, validate that deprecation_date is a parseable date, affected_endpoints contains valid API path patterns, and migration_guidance is non-empty when breaking_change is true. Implement a schema validator (JSON Schema or Pydantic model) that rejects records with missing required fields. For high-stakes tool platforms, add a second validation pass that checks extracted dates against known deprecation timelines in your API version registry to catch hallucinated dates. Records that fail validation should be routed to a dead-letter queue for human review, not silently dropped.

Model choice matters for this task. Use a model with strong structured extraction capabilities and a context window large enough to hold the full changelog chunk plus the prompt template. Claude 3.5 Sonnet and GPT-4o are both effective; avoid smaller or older models that struggle with multi-entity extraction from dense technical text. Set temperature=0 or very low (0.1) to maximize consistency across runs. If you're processing changelogs at scale, implement a caching layer keyed on the content hash of each chunk to avoid re-extracting unchanged content. For changelogs that reference external migration guides via URL, consider adding a tool that fetches and summarizes the linked page, but gate this behind a rate limit and domain allowlist to prevent unbounded external calls.

Implement a retry strategy with care. If the model returns malformed JSON, retry once with the validation error message appended to the prompt as feedback. If the second attempt also fails, log the raw response and chunk for manual triage. Do not retry more than twice; the cost of repeated failures on the same malformed input rarely justifies the token spend. For changelogs that contain no deprecation notices, the prompt should return an empty list, not an error. Your harness should distinguish between 'no deprecations found' (valid empty result) and 'extraction failed' (error state) to avoid false negatives in your deprecation monitoring.

Human review should be triggered for three conditions: (1) validation failures after retries, (2) extracted deprecation dates that fall within the next 30 days (urgency gate), and (3) records where confidence or a similar self-assessment field falls below a threshold you define (e.g., 0.8). Route these to a review queue with the source changelog chunk, the extracted record, and any validation error context. The reviewer should confirm, correct, or reject the extraction. Accepted records feed into your deprecation registry; rejected records should be annotated with the reason to improve future prompt iterations. This human-in-the-loop step is critical for tool platforms where a missed deprecation can cause production agent failures.