OpenAPI Specifications and Developer Tools

Direct Access to the OpenAPI Specification

The complete and formal API contract is defined using the OpenAPI 3.1.0 specification. This file represents the source of truth for all endpoints, methods, parameters, data schemas, and security requirements. We recommend using it as a primary reference during development.

Specification Download Link:

https://www.taoticket.com/.well-known/openapi.yaml

Leveraging the OpenAPI Specification

Proactive use of the openapi.yaml file can significantly speed up the integration process and increase the robustness of client code.

Importing into API Tools: The file can be imported directly into development and testing tools such as Postman or Insomnia. This process will automatically generate a complete collection of all API requests, pre-configured with the correct URLs, HTTP methods, headers (including a placeholder for Authorization), and the JSON body structure. This eliminates the need to manually configure each call.

Generating Type-Safe API Clients: For more advanced and secure integration, we recommend using code generators such as openapi-generator-cli. These tools read the openapi.yaml file and generate a complete, strongly typed API client in the desired programming language (e.g., Python, TypeScript, Java, Go, etc.). Using a generated client offers numerous advantages:

It eliminates the need to manually write HTTP calls.

It automatically handles serialization (from objects to JSON) and deserialization (from JSON to objects).

It provides a type-safe programming interface, with autocompletion and compile-time type checking, dramatically reducing the risk of errors.

Section 4: Detailed Endpoint Reference

This section provides a detailed description of each available endpoint, complete with parameters, descriptions, and practical code examples.

4.1 Endpoint: Cruise Search (find-cruises)

POST /mcp/tools/find-cruises

Functional Description: This is the main tool for querying Taoticket's cruise catalog. It allows for flexible searches based on a combination of criteria, as specified in the OpenAPI description: "Useful for finding specific cruises by port, company, geographic area, or period."

Request Parameters: All parameters are optional and can be combined to refine the search.

Create a new POST request to the URL https://www.taoticket.com/mcp/tools/find-cruises.

In the Authorization tab, select the "Bearer Token" type and paste your API key in the "Token" field.

In the Headers tab, ensure there is a Content-Type key with the value application/json.

In the Body tab, select the raw option and the JSON format. Enter the request payload.

4.2 Endpoint: Ship Information (info-nave)

POST /mcp/tools/info-nave

Functional Description: This endpoint is a specific tool for retrieving technical data, descriptions, and features for a single cruise ship, when its name is already known.

4.3 Endpoint: FAQ Search (cerca-faq)

POST /mcp/tools/cerca-faq

Functional Description: This tool acts as a semantic search engine based on the knowledge base of Taoticket's Frequently Asked Questions (FAQ). As indicated in the OpenAPI description, it is intended to answer general questions about policies, procedures, and practical information ("what documents are required," "how does payment work"), and should not be used to search for itineraries or cruises.