Versions — MCP Tools
Spec versions: lifecycle, publishing, promotion and environment pins. This page documents the Versions group of the Routebase MCP server, with the scope and the parameters of each tool.
A session that stages its tools advertises this group once the agent calls enable_toolset with the slug versions. Full-access keys, scoped keys and OAuth sessions see every tool they are allowed to call without that step.
cancel_scheduled_publish
Cancel a scheduled publish that has not run yet. Get its ID from get_scheduled_publishes. 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 version |
scheduledPublishId |
string | Yes | Public ID (GUID) of the scheduled publish to cancel |
compare_versions
Compare two specification versions and show their differences: added/removed/modified endpoints and schemas. Omit sourceVersionId to compare against the latest published version. detail 'full' (default) returns the changed entities; 'flags' returns only what changed and how — much smaller, and enough to decide where to look. Requires project context. Use this for the raw structural difference; for a written summary of it use generate_changelog.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
targetVersionId |
string | Yes | Public ID (GUID) of the target (newer) version |
sourceVersionId |
string | No | Public ID (GUID) of the source (older) version — omit for the latest published version |
detail |
string | No (default "full") |
How much to return: 'full' (default) or 'flags' |
create_version
Create a new version of an API specification. By default, copies content from the latest version. Set createEmpty=true for an empty version, or specify copyFromVersionId to copy from a specific version. Use this to start the next version; to move an existing one through its lifecycle use manage_version_status. Requires project context.
Required scope: specs:write
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionNumber |
string | Yes | Semantic version number (e.g., '2.0.0') |
releaseNotes |
string | No | Optional release notes for this version |
copyFromVersionId |
string | No | Public ID (GUID) of a specific version to copy content from |
copyFromLatest |
boolean | No (default true) |
If true (default), copies from the latest version when copyFromVersionId is not set |
createEmpty |
boolean | No (default false) |
If true, creates an empty version without copying any content (default false) |
delete_version
Delete a spec version and everything in it — endpoints, schemas, folders and tags of that version. Use this to drop one version; to remove the spec with all its versions use delete_spec. Requires project context.
Required scope: specs:delete
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionId |
string | Yes | Public ID (GUID) of the version to delete |
generate_changelog
Generate a structured changelog for a specification version by comparing it with the previous version. Returns a Markdown changelog. Use this for a readable summary of what changed; for the raw structural diff use compare_versions. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionId |
string | Yes | Public ID (GUID) of the version to generate a changelog for |
get_environment_pins
List which version each environment currently pins for this spec, whether the pin is frozen, and where it came from. Use this to see what each environment resolves to; to change a pin use promote_version. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
get_publish_history
List when a version was published, to which target and by whom. Use this for what has already been published; for publishes still ahead use get_scheduled_publishes. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionId |
string | Yes | Public ID (GUID) of the version |
skip |
integer | No (default 0) |
Number of entries to skip (default 0) |
take |
integer | No (default 50) |
Number of entries to return (default 50, max 100) |
get_scheduled_publishes
List the scheduled publishes of a version. Pending ones by default; pass includeExecuted or includeCancelled to see the rest. Use this for publishes that have not run yet; for those already done use get_publish_history. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionId |
string | Yes | Public ID (GUID) of the version |
includeExecuted |
boolean | No (default false) |
Include schedules that already ran (default false) |
includeCancelled |
boolean | No (default false) |
Include cancelled schedules (default false) |
get_version
Get one spec version with its status, release notes, alias, publish and deprecation timestamps, and the rowVersion needed to edit it. Use this when you already have the version id; to browse a spec's versions or find an id use list_versions. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionId |
string | Yes | Public ID (GUID) of the version |
list_versions
List all versions of an API specification with their status (draft/review/published/deprecated). Set includeSuggestions for the next major, minor and patch number under this spec's versioning strategy — what create_version expects. Use this to browse versions or find a version id; for one version by id use get_version. Requires project context (call set_context first).
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
skip |
integer | No (default 0) |
Number of versions to skip (for pagination, default 0) |
take |
integer | No (default 50) |
Number of versions to return (default 50, max 100) |
includeSuggestions |
boolean | No (default false) |
Also return the suggested next version numbers (default false) |
manage_version_status
Move a spec version through its lifecycle. Actions: 'submit_for_review' (draft → review), 'return_to_draft' (review or published → draft, making it editable again), 'deprecate' (mark a published version as deprecated; consumers are warned but it stays readable) or 'unpublish' (withdraw it from the portal). Use publish_version to publish. 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 version |
action |
string | Yes | What to do: 'submit_for_review', 'return_to_draft', 'deprecate' or 'unpublish' |
pre_publish_impact
Check what publishing or promoting this version would do to dependent projects: how many are affected, at which severity, and whether the impact has to be acknowledged. Run this before promote_version when the version carries breaking changes. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionId |
string | Yes | Public ID (GUID) of the version to analyse |
promote_version
Pin a version to an environment — what that environment's consumers, mocks and contract tests resolve to. If the impact analysis flags breaking changes for dependents, the call is refused until acknowledgeImpact is set; run pre_publish_impact first and read the result rather than acknowledging blind. Needs 'specs:write'; promoting into an environment that freezes versions is a release and additionally needs 'specs:publish'. 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 version to promote |
environmentId |
string | Yes | Public ID (GUID) of the target environment |
publishTarget |
string | No (default "internal") |
Publish target: 'internal', 'public' or 'export_only' (default 'internal') |
acknowledgeImpact |
boolean | No (default false) |
Acknowledge a flagged breaking-change impact and promote anyway (default false) |
publish_version
Publish a specification version. Transitions from Draft or Review to Published status and creates an immutable OpenAPI snapshot. Use this to publish now; to publish at a future time use schedule_publish. 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 version to publish |
publishTarget |
string | No (default "internal") |
Publish target: 'internal' (default), 'public', or 'exportOnly' |
rollback_environment_pin
Roll an environment's pin back to the version it held before the last promotion. Needs 'specs:write'; rolling back an environment that freezes versions is a release and additionally needs 'specs:publish'. Requires project context.
Required scope: specs:write
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
environmentId |
string | Yes | Public ID (GUID) of the environment whose pin should roll back |
schedule_publish
Schedule a version to publish at a future time instead of publishing now. Returns the scheduled publish ID, which cancel_scheduled_publish takes. Needs 'specs:write'; without an environmentId the schedule publishes the version outright and additionally needs 'specs:publish', as does scheduling into an environment that freezes versions. 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 version to publish |
scheduledFor |
string | Yes | When to publish, as an ISO-8601 UTC timestamp (e.g. '2026-08-01T09:00:00Z'). Must be in the future. |
publishTarget |
string | No (default "internal") |
Publish target: 'internal', 'public' or 'export_only' (default 'internal') |
releaseNotes |
string | No | Optional release notes to attach when it publishes |
environmentId |
string | No | Optional environment ID (GUID) to pin the version to on publish |
set_version_alias
Set or clear a version's alias — a stable name like 'latest' or 'stable' that consumers and the documentation portal can point at instead of a version number. Pass an empty string to clear it. An alias is unique per spec: setting it moves it off whichever version held it. 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 version |
alias |
string | Yes | The alias (e.g. 'latest'); empty string removes the alias from this version |
update_version
Update a version's release notes. Pass an empty string to clear them. Get the version's rowVersion from get_version. 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 version |
rowVersion |
string | Yes | Base64-encoded row version (for concurrency control), from get_version |
releaseNotes |
string | Yes | New release notes (Markdown); empty string clears them |