For AI agents: the complete documentation index is at https://docs.routebase.dev/llms.txt. Every page is also available as Markdown by appending index.md to its URL or by sending Accept: text/markdown.
MCP Reference

API Specifications — MCP Tools

Create, read, update and delete API specifications. This page documents the API Specifications group of the Routebase MCP server, with the scope and the parameters of each tool.

The group is part of the core set, so every session advertises it from the start.

create_spec

Create a new API specification in the active project. Returns the id of the automatically created initial draft version — use it as versionId when creating endpoints. Use this for a new empty spec; to bring an existing OpenAPI document into the project use import_spec. Requires project context.

Required scope: specs:write

Parameter Type Required Description
name string Yes Name of the API specification
version string Yes Version string (e.g., '1.0.0')
openApiVersion string No (default "v3_2") OpenAPI version: 'v3_0', 'v3_1' or 'v3_2' (default 'v3_2')
description string No Optional description of the API

delete_spec

Delete an API specification and everything under it — versions, endpoints, schemas, folders and tags. Use this to remove the whole spec; to drop a single version only use delete_version. Requires project context.

Required scope: specs:delete

Parameter Type Required Description
specId string Yes Public ID (GUID) of the API specification to delete

export_spec

Export an API specification as OpenAPI YAML, JSON, or Postman Collection. Use this to get the finished document out; to check it against the standard first use validate_spec. Requires project context.

Required scope: specs:read

Parameter Type Required Description
specId string Yes Public ID (GUID) of the API specification to export
format string No (default "yaml") Export format: 'yaml' (default), 'json', or 'postman'

get_spec

Get detailed information about an API specification, including whether its documentation is internal, authenticated or public and under which slug. Includes the spec's versions (newest first, up to 10) — use their id as versionId for create_endpoint and other version-scoped tools. Use this when you already have the spec id; to browse the project's specs or find an id use list_specs. Requires project context.

Required scope: specs:read

Parameter Type Required Description
specId string Yes Public ID (GUID) of the API specification

import_spec

Import an OpenAPI specification from YAML or JSON content into the active project. Use this to bring an existing OpenAPI document in; to start from an empty spec use create_spec. Requires project context.

Required scope: specs:write

Parameter Type Required Description
content string Yes The OpenAPI specification content (YAML or JSON string)
format string No Format hint: 'yaml', 'json', or omit for auto-detection
validateOnly boolean No (default false) If true, only validate without importing (default false)
convertToOpenApi31 boolean No (default false) Convert OpenAPI 3.0 to 3.1 during import (default false)
createFoldersFromTags boolean No (default false) Create folders from OpenAPI tags (default false)
shortenSchemaNames boolean No (default false) Shorten schema names to the last dot-segment when unique within the spec (default false)
discardOriginalSchemaNames boolean No (default false) With shortenSchemaNames: permanently discard the cut namespace segments — original names are not stored; re-imports/diffs against the source file will report renames (default false)

list_specs

List all API specifications in the active project. Set scope to 'org' to list the published APIs across every project in the organization instead — each entry carries the projectId and specId to pass to set_context. Use this to browse specs or find a spec id; for one spec by id use get_spec. Requires project context for scope 'project'.

Required scope: specs:read

Parameter Type Required Description
skip integer No (default 0) Number of specs to skip (for pagination, default 0)
take integer No (default 50) Number of specs to return (default 50, max 100)
scope string No (default "project") What to list: 'project' (default) or 'org'

update_spec

Update an API specification's metadata: name, version string, description, base path or server URL. Omit a field to keep its current value; pass an empty string to clear description, basePath or serverUrl (name and version cannot be empty). Get the spec's rowVersion from get_spec. Requires project context.

Required scope: specs:write

Parameter Type Required Description
specId string Yes Public ID (GUID) of the API specification
rowVersion string Yes Base64-encoded row version of the spec (for concurrency control), from get_spec
name string No New name, or omit to keep the current name
version string No New version string (e.g. '2.0.0'), or omit to keep the current one
description string No New description; empty string clears it, omit to keep the current one
basePath string No New base path (e.g. '/v2'); empty string clears it, omit to keep the current one
serverUrl string No New server URL (absolute HTTPS); empty string clears it, omit to keep the current one
selfUri string No 3.2 only: document $self URI; omit keeps, empty string clears

validate_spec

Validate an OpenAPI specification against the standard. Provide either content to validate directly, or specId to validate an existing spec. Set mode to 'import' for a dry run of import_spec instead: same errors and warnings, plus what would be created (endpoint, schema and folder counts), the detected format and whether a 3.0 → 3.1 conversion happened. Nothing is written either way.

Required scope: specs:read

Parameter Type Required Description
content string No The OpenAPI specification content to validate (YAML or JSON). Provide either content or specId, not both.
specId string No Public ID (GUID) of an existing spec to validate. If provided, the spec is exported first and then validated.
format string No Format hint: 'yaml', 'json', or omit for auto-detection
mode string No (default "openapi") What to check: 'openapi' (default) or 'import'
convertToOpenApi31 boolean No (default false) For mode 'import': convert a 3.0 document to 3.1 (default false)
shortenSchemaNames boolean No (default false) For mode 'import': shorten generated schema names (default false)