Deprecation — MCP Tools
10 tools in the Deprecation group of the Routebase MCP server.
force_advance_deprecation
Push a deprecation one phase further than its schedule allows — grace period to sunset phase, or sunset phase to retired — skipping the checks that hold it back. Only from those two phases, and the justification is recorded in the audit trail. Requires project context.
Required scope: org:manage-governance
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
entityType |
string | Yes | What is deprecated: 'endpoint' or 'specVersion' |
entityId |
string | Yes | Public ID (GUID) of that endpoint or version |
justification |
string | Yes | Why the schedule is being overridden — recorded in the audit trail |
get_deprecation_plan
Get the deprecation plan of one endpoint or published version, including its phase, sunset date, successor and migration guide. Returns null when nothing is deprecated. Set includeUsage to also see whether anyone still calls it — do that before retiring. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
entityType |
string | Yes | What is deprecated: 'endpoint' or 'specVersion' |
entityId |
string | Yes | Public ID (GUID) of that endpoint or version |
includeUsage |
boolean | No (default false) |
Also return recent traffic and top consumers (default false) |
usageDaysBack |
integer | No (default 30) |
How many days of usage to look back (default 30) |
get_deprecation_policy
Get the organization's deprecation policy: the minimum grace period, whether a migration guide, a successor or an approval is required, and the reminder schedule. These are the rules manage_deprecation_plan('create') is checked against. Requires organization context.
Required scope: specs:read
No parameters.
list_deprecations
List everything currently deprecated across the organization — endpoints and published versions — with the phase, the sunset date and how many days are left. The starting point for 'what do I have to migrate off'. Requires organization context.
Required scope: specs:read
No parameters.
manage_deprecation_plan
Announce, change or take back a deprecation. 'create' needs entityType, entityId and sunsetAt, and the organization's policy decides whether a migration guide or a successor is mandatory and how far out the sunset must be; if the policy requires approval the plan starts as pendingApproval and nothing is marked deprecated until review_deprecation_plan approves it. 'update' can only push sunsetAt further out, never closer. 'cancel' takes the deprecation back and un-deprecates the entity — that is different from retire_deprecation, which ends it early and keeps it deprecated. Requires project context.
Required scope: specs:write
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
action |
string | Yes | What to do: 'create', 'update' or 'cancel' |
entityType |
string | No | What is deprecated: 'endpoint' or 'specVersion' — required for 'create' |
entityId |
string | No | Public ID (GUID) of that endpoint or version — required for 'create' |
planId |
string | No | Public ID (GUID) of the plan — required for 'update' and 'cancel' |
sunsetAt |
string | No | When it goes away, ISO 8601 (e.g. '2027-01-31T00:00:00Z') — required for 'create', and for 'update' only a later date is accepted |
successorEndpointId |
string | No | Public ID (GUID) of the endpoint that replaces this one |
successorSpecId |
string | No | Public ID (GUID) of the spec that replaces this one |
migrationGuide |
string | No | Migration instructions for consumers |
updateSuccessor |
boolean | No (default false) |
For 'update': apply the successor fields, including clearing them when both are omitted (default false — successors stay untouched) |
enableRateLimiting |
boolean | No | Throttle the deprecated endpoint once it enters the sunset phase |
rateLimitReductionPercent |
integer | No | By how many percent to cut the configured rate limit, when rate limiting is on (1-100; 90 leaves a tenth of the original limit) |
enableWarningHeader |
boolean | No | Send the RFC 8594 deprecation warning header |
autoShutdown |
boolean | No | Shut the endpoint down automatically at the sunset date |
softShutdownDays |
integer | No | Days of intermittent shutdown before the hard one, as a warning to consumers |
notify_dependent_owners
Notify the owners of everything that depends on a version that it is going away. Sends real messages — call it once the deprecation is decided, not while exploring. Requires project context.
Required scope: specs:publish
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionId |
string | Yes | Public ID (GUID) of the spec version |
retire_deprecation
End a deprecation early: the entity stays deprecated and the sunset date stops mattering. Refuses while consumers called it in the last seven days unless confirmActiveConsumers is set — check get_deprecation_plan(includeUsage) first. To take a deprecation back instead, use manage_deprecation_plan('cancel'). Requires project context.
Required scope: specs:delete
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
planId |
string | Yes | Public ID (GUID) of the deprecation plan |
confirmActiveConsumers |
boolean | No (default false) |
Retire even though consumers are still calling it (default false) |
review_deprecation_plan
Approve or reject a deprecation plan that is waiting for approval. Approving is what actually marks the endpoint or version as deprecated and starts the clock. Rejecting is final and needs a comment. Requires project context.
Required scope: specs:publish
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
planId |
string | Yes | Public ID (GUID) of the deprecation plan |
action |
string | Yes | What to do: 'approve' or 'reject' |
comment |
string | No | Why it was rejected — required for 'reject' |
set_version_sunset
Set or clear the sunset date of a published version directly, without a deprecation plan. Omit sunsetAt to clear it. This is the plain date on the version — the phased lifecycle with approval and usage checks is manage_deprecation_plan. Requires project context.
Required scope: specs:write
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionId |
string | Yes | Public ID (GUID) of the spec version |
sunsetAt |
string | No | The sunset date, ISO 8601 — omit to clear it |
update_deprecation_policy
Change the organization's deprecation policy. Every field is optional and only what you pass is changed. Passing preset ('relaxed', 'standard' or 'strict') sets grace period, sunset phase and the three requirement flags in one go. Applies to every project in the organization. Requires organization context.
Required scope: org:manage-governance
| Parameter | Type | Required | Description |
|---|---|---|---|
minGracePeriodDays |
integer | No | Shortest allowed time between announcing and sunsetting, in days |
sunsetPhaseDays |
integer | No | How long the sunset phase lasts, in days |
requireMigrationGuide |
boolean | No | Refuse plans without a migration guide |
requireSuccessorLink |
boolean | No | Refuse plans without a successor link |
requireApproval |
boolean | No | Make new plans wait for approval before anything is marked deprecated |
notifyOnAnnouncement |
boolean | No | Notify consumers when a deprecation is announced |
sendSunsetReminders |
boolean | No | Send reminders as the sunset approaches |
reminderDaysJson |
string | No | Reminder offsets in days before sunset, as a JSON array (e.g. '[30,7,1]') |
preset |
string | No | Apply a preset: 'relaxed', 'standard' or 'strict' |