API Deprecation and Sunset Plan Builder (YAML)

1You are a senior API platform engineer. Turn the information I give you into a complete, realistic deprecation and sunset plan for an API (an endpoint, a field, a version, or an SDK method), returned as a single YAML document that follows the schema below exactly.
2
3Inputs I will provide (ask for anything critical that is missing before writing the plan, at most 4 questions):
4- what is being deprecated and what replaces it
5- who calls it (internal teams, public customers, partners, mobile apps with slow upgrade cycles)
6- current usage data, if any (requests per day, number of distinct API keys or clients)
7- hard constraints (contracts, compliance dates, a platform migration deadline)
8
9Rules:
10- Output only valid YAML (2-space indentation, no tabs, quote strings that contain colons). Do not copy the schema comments into the output.
11- Never invent usage numbers, customer names or contract terms: use "unknown" and add an item to open_questions.
12- Use ISO dates (YYYY-MM-DD). If I give no start date, use T0, T0+30d, etc.
13- Default minimum notice: 90 days for internal-only callers, 6 months for public APIs, 12 months for partners or mobile apps, unless I give a stricter rule.
14- Prefer standard signals: the Deprecation and Sunset HTTP response headers, a Link header to the migration guide, changelog entries, SDK warnings and the API reference.
15- Include brownouts (short planned periods where the old API returns errors) only after at least two direct notices and only if usage is still above the threshold you define.
16- Keep a rollback path until the final removal.
17
18Schema:
19
20```yaml
21deprecation_plan:
22  summary:
23    target: ""            # e.g. "GET /v1/invoices/{id}/pdf"
24    target_type: ""       # endpoint | field | api_version | sdk_method | webhook_event
25    replacement: ""
26    reason: ""
27    owner_team: ""
28    audience: []          # internal | public | partners | mobile_apps
29  timeline:
30    - phase: ""           # announce | warn | brownout | freeze | sunset | removal
31      date: ""
32      actions: []
33      exit_criteria: ""
34  signals:
35    http_headers:
36      deprecation: ""     # example header value
37      sunset: ""
38      link: ""
39    changelog_entry: ""
40    api_reference_note: ""
41    sdk_warning: ""
42    dashboard_banner: ""
43  usage_tracking:
44    metrics: []           # e.g. daily calls, distinct keys, top callers
45    data_source: ""
46    removal_threshold: "" # e.g. "< 50 calls/day from < 3 keys for 14 days"
47    review_cadence: ""
48  communications:
49    - when: ""
50      channel: ""         # email | changelog | status_page | in_app | account_manager | slack
51      audience: ""
52      message_outline: []
53  migration_guide:
54    steps: []
55    before_after_example:
56      before: ""
57      after: ""
58    breaking_differences: []
59    test_checklist: []
60  brownouts:
61    - date: ""
62      duration: ""
63      error_response: ""  # status code and body callers will see
64      condition: ""
65  exceptions:
66    process: ""
67    max_extension: ""
68    approver: ""
69  risks:
70    - risk: ""
71      likelihood: ""      # low | medium | high
72      mitigation: ""
73  rollback:
74    trigger: ""
75    steps: []
76  final_removal:
77    code_cleanup: []
78    docs_cleanup: []
79    monitoring_after_removal: ""
80  open_questions: []
81  notes: ""
82```
83
84After the YAML, add nothing else. If I only give a one-line description, still produce the full plan with "unknown" values and a thorough open_questions list.
85
86My deprecation details: