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

Schemas — MCP Tools

Schemas within a spec. This page documents the Schemas 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 schemas. Full-access keys, scoped keys and OAuth sessions see every tool they are allowed to call without that step.

create_schema

Create a new reusable schema in an API specification. The schema can then be referenced by endpoints, request bodies, and responses. Use this for a new reusable schema; to point existing inline copies at it afterwards use migrate_schema_links. 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 to add the schema to
name string Yes Schema name (e.g., 'User', 'ErrorResponse', 'PaginatedList')
jsonSchema string Yes JSON Schema definition as a string (e.g., '{"type":"object","properties":{...}}')
description string No Description of the schema

delete_schema

Delete a schema (soft delete). This does NOT check references — a schema still used by endpoints, request bodies or responses is deleted anyway, and every one of them becomes a review item. Call get_schema with includeUsage first and clear the references you do not want to break. 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 spec version
schemaId string Yes Public ID (GUID) of the schema to delete

get_schema

Get detailed information about a schema including its full JSON Schema definition. Optionally include usage details showing which endpoints reference it. Use this when you already have the schema id; to browse a spec's schemas or find an id use list_schemas. Requires project context.

Required scope: specs:read

Parameter Type Required Description
specId string Yes Public ID (GUID) of the API specification
schemaId string Yes Public ID (GUID) of the schema
includeUsage boolean No (default false) Include usage details showing which endpoints reference this schema (default false)

list_schemas

List all schemas of an API specification. Optionally include usage counts showing how many endpoints reference each schema. Set scope to 'project' to look across every spec in the project instead — that returns the groups of structurally identical schemas (candidates for the shared library) plus counts, not the full list, and specId is then ignored. Every entry carries the rowVersion update_schema needs, so a batch of updates does not need a get_schema per schema first. Use this to browse schemas or find a schema id; for one schema with its full definition use get_schema. Requires project context.

Required scope: specs:read

Parameter Type Required Description
specId string Yes Public ID (GUID) of the API specification
versionId string No Optional version ID (GUID) to filter schemas by a specific version
includeUsageCounts boolean No (default false) Include usage counts per schema (default false, slightly slower)
scope string No (default "spec") What to look at: 'spec' (default) or 'project'

Find inline request bodies, responses and parameters across a spec that match an existing reusable component and link them to it, so the shape lives in one place. ALWAYS run with dryRun first and read the report — the matching is similarity-based, and a run with dryRun false rewrites every match it found. Use this to replace matching inline copies with a reference; to create the schema itself use create_schema. Requires project context.

Required scope: specs:write

Parameter Type Required Description
specId string Yes Public ID (GUID) of the API specification
dryRun boolean No (default true) Report what would change without writing anything (default true). Set false only after reviewing a dry run.
minimumSimilarity number No (default 0.9) How close a match has to be, 0.0–1.0 (default 0.9). Lower values link more aggressively and are more likely to link things that only look alike.

restore_schema

Restore a soft-deleted schema into its version. Use this to bring a soft-deleted schema back; to remove one use delete_schema. 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 the schema belongs to
schemaId string Yes Public ID (GUID) of the deleted schema

update_schema

Update an existing schema. Requires the rowVersion from get_schema for optimistic concurrency control (Base64-encoded string). 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
schemaId string Yes Public ID (GUID) of the schema to update
name string Yes Schema name
jsonSchema string Yes JSON Schema definition as a string
rowVersion string Yes Base64-encoded row version from get_schema (for concurrency control)
description string No Description of the schema