Versions — MCP Tools
18 tools in the Versions group of the Routebase MCP server.
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.
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. 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. 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. 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. 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. 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. 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. 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. 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. 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 |