Load and parse an OpenAPI (Swagger) specification document from a URL.

This tool fetches a JSON OpenAPI/Swagger spec from the given URL and stores it in memory for subsequent exploration. You must load a spec before using any other tools.

Each loaded spec is assigned a unique name (title + version). If a spec with the same name already exists, a numeric suffix is appended.

Args:

• url (string): URL to the OpenAPI/Swagger JSON spec (e.g., "https://petstore.swagger.io/v2/swagger.json")

• auth_header (string, optional): Authorization header value for protected specs (e.g., "Bearer token123" or "Basic base64encoded"). Only needed for authenticated endpoints.

Returns: { "spec_name": string, // The assigned spec name for subsequent tools "title": string, // API title from the spec "version": string, // API version from the spec "description": string, // API description (if available) "endpoints": number, // Total number of API endpoints found "schemas": number, // Total number of schemas/components found "tags": number, // Total number of unique tags found "server_url": string // Base server URL from the spec }

Examples:

• Use when: "Load the Petstore API spec" -> params with url="https://petstore.swagger.io/v2/swagger.json"

• Use when: "Load our internal API docs" -> params with url="https://api.internal.company.com/openapi.json"

Error Handling:

• Returns error if URL is unreachable or times out

• Returns error if the document is not valid OpenAPI/Swagger JSON

• Returns error if YAML format is provided (only JSON is supported)

Load and parse an OpenAPI (Swagger) specification document from a local JSON file.

This tool reads a JSON OpenAPI/Swagger spec from a local file path and stores it in memory for subsequent exploration. The file path can be absolute or relative to the current working directory.

Each loaded spec is assigned a unique name (title + version). If a spec with the same name already exists, a numeric suffix is appended.

Args:

• file_path (string): Path to a local OpenAPI/Swagger JSON file (e.g., "./swagger.doc.json" or "/path/to/api-spec.json")

Returns: { "spec_name": string, // The assigned spec name for subsequent tools "title": string, // API title from the spec "version": string, // API version from the spec "description": string, // API description (if available) "endpoints": number, // Total number of API endpoints found "schemas": number, // Total number of schemas/components found "tags": number, // Total number of unique tags found "server_url": string // Base server URL from the spec }

Examples:

• Use when: "Load the local swagger.doc.json" -> params with file_path="./swagger.doc.json"

• Use when: "Load our API spec from disk" -> params with file_path="/home/user/projects/api/openapi.json"

Error Handling:

• Returns error if the file path does not exist

• Returns error if the file is not valid JSON

• Returns error if the JSON is not a valid OpenAPI/Swagger spec

List all currently loaded OpenAPI/Swagger specifications in memory.

Use this tool to see which specs have been loaded and are available for exploration.

Args: None

Returns: { "loaded": [ // Array of loaded specs { "name": string, "title": string, "version": string, "source": string, "loaded_at": string } ] }

Examples:

• Use when: "What specs have I loaded?" -> no params needed

• Use when: "Show my loaded APIs" -> no params needed

Remove a loaded OpenAPI/Swagger specification from memory.

Use this tool to free up memory or reload a spec that has changed.

Args:

• spec_name (string): Name of the spec to remove

Returns: Confirmation message.

Examples:

• Use when: "Remove the Petstore API spec" -> params with spec_name="Petstore v1.0.0"

• Use when: "Unload the internal API spec" -> params with spec_name="Internal API v2.0"

Error Handling:

• Returns error if the spec name is not found

List all API endpoints (paths and HTTP methods) from a loaded OpenAPI spec, optionally filtered by tag.

Use this tool to get a high-level overview of all available API operations. Results can be filtered by tag for progressive exploration.

Args:

• spec_name (string): Name of the previously loaded spec

• tag (string, optional): Filter endpoints by this tag/group name

• limit (number): Maximum results to return, between 1-200 (default: 50)

• offset (number): Number of results to skip for pagination (default: 0)

Returns: { "total": number, // Total number of matching endpoints "count": number, // Number of results in this response "offset": number, // Current pagination offset "endpoints": [...], "has_more": boolean, "next_offset": number }

Examples:

• Use when: "Show me all endpoints" -> params with spec_name=""

• Use when: "List all user-related endpoints" -> params with spec_name="", tag="users"

Error Handling:

• Returns error if the spec name has not been loaded yet

Get detailed information about a specific API endpoint, including parameters, request body, responses, and security requirements.

Use this tool after swagger_list_paths to drill down into a specific endpoint's complete details.

Args:

• spec_name (string): Name of the previously loaded spec

• path (string): URL path of the endpoint (e.g., "/pets/{petId}")

• method (string): HTTP method (get, post, put, patch, delete, options, head)

Returns: Full endpoint details with parameters, request body, responses, and security.

Examples:

• Use when: "Show me the details of GET /pets/{petId}" -> params with spec_name="", path="/pets/{petId}", method="get"

• Use when: "What parameters does the create user endpoint take?" -> params with spec_name="", path="/users", method="post"

Error Handling:

• Returns error if the spec name has not been loaded

• Returns error if the path or method is not found, with suggestions

Get detailed information about a specific API endpoint with all schema references ($ref) recursively resolved.

Unlike swagger_get_endpoint, this tool resolves every $ref into its full schema definition. Parameters, request body schemas, and response schemas are expanded inline with no external references. Circular references are detected and marked.

Use this when you need the complete endpoint definition in a single call, without needing to follow $ref links manually.

Args:

• spec_name (string): Name of the previously loaded spec

• path (string): URL path of the endpoint (e.g., "/pets/{petId}")

• method (string): HTTP method (get, post, put, patch, delete, options, head)

Returns: Full endpoint details with all $ref resolved recursively.

Examples:

• Use when: "Show me everything about GET /pets/{petId} with all schemas expanded" -> params with spec_name="", path="/pets/{petId}", method="get"

• Use when: "Give me the full request body schema for creating a user" -> params with spec_name="", path="/users", method="post"

Error Handling:

• Returns error if the spec name has not been loaded

• Returns error if the path or method is not found, with suggestions

List all component schemas (data models) defined in the loaded OpenAPI spec.

Use this tool to get an overview of all data models used by the API, including their types and number of properties.

Args:

• spec_name (string): Name of the previously loaded spec

• limit (number): Maximum results to return (default: 50)

• offset (number): Number of results to skip (default: 0)

Returns: { "total": number, // Total number of schemas "count": number, // Number of results in this response "offset": number, // Current pagination offset "schemas": [{ "name", "type", "description", "properties" }], "has_more": boolean, "next_offset": number }

Examples:

• Use when: "What data models are defined?" -> params with spec_name=""

• Use when: "Show me all schemas" -> params with spec_name=""

Error Handling:

• Returns error if the spec name has not been loaded yet

Get detailed information about a specific component schema (data model), including all properties, types, constraints, and examples.

Use this tool to drill down into a specific data model after using swagger_list_schemas.

Args:

• spec_name (string): Name of the previously loaded spec

• schema_name (string): Name of the schema/model (e.g., "Pet", "User", "Order", "Error")

Returns: Formatted output with the full schema definition including type, properties, required fields, enums, constraints, and examples.

Examples:

• Use when: "Show me the Pet model" -> params with spec_name="", schema_name="Pet"

• Use when: "What fields does the User schema have?" -> params with spec_name="", schema_name="User"

Error Handling:

• Returns error if the spec name has not been loaded

• Returns error if the schema name is not found, suggesting available schemas

Get general information about a loaded OpenAPI/Swagger specification, including title, version, description, server URL, contact info, and license.

Use this tool to get a high-level summary of an API spec.

Args:

• spec_name (string): Name of the previously loaded spec (use swagger_list_loaded to see available names)

Returns: { "title": string, // API title "version": string, // API version "description": string, // API description "server_url": string, // Base server URL "endpoints": number, // Total endpoint count "schemas": number, // Total schema count "tags": number, // Total tag count "openapi_version": string // OpenAPI spec version }

Examples:

• Use when: "Tell me about this API" -> params with spec_name=""

• Use when: "What's the base URL for this API?" -> params with spec_name=""

Error Handling:

• Returns error if the spec name has not been loaded

List all API tags/groups and their associated endpoint counts from a loaded OpenAPI spec.

Tags are used to group related endpoints. This tool helps with progressive exploration by showing available filter categories.

Args:

• spec_name (string): Name of the previously loaded spec

Returns: { "tags": [{ "name": string, "count": number }] }

Examples:

• Use when: "What tags/groups are available?" -> params with spec_name=""

• Use when: "How are the endpoints organized?" -> params with spec_name=""

Error Handling:

• Returns error if the spec name has not been loaded

Search across all endpoints and schemas in a loaded OpenAPI spec for a given query string.

Searches through endpoint paths, operation summaries, operationIds, descriptions, tags, schema names, and property names.

Args:

• spec_name (string): Name of the previously loaded spec

• query (string): Search term to find in endpoint paths, summaries, operationIds, tags, schema names, and property descriptions

Returns: { "total": number, // Total number of matches "results": [ { "type": "endpoint" | "schema" | "property", "path": string, // URL path (for endpoints) "method": string, // HTTP method (for endpoints) "schemaName": string, // Schema name (for schemas/properties) "propertyName": string, // Property name (for properties) "match": string, // Human-readable match description "summary": string // Brief description } ] }

Examples:

• Use when: "Search for anything about pets" -> params with spec_name="", query="pet"

• Use when: "Find endpoints related to users" -> params with spec_name="", query="user"

Error Handling:

• Returns error if the spec name has not been loaded