Guide

Use API documentation when there is no OpenAPI file

Your API does not need to publish an OpenAPI document. Give your connected agent usable endpoint documentation or request examples. It can write a small document for the operation you need, then validate and import it through Oatty.

Start with API access to install Oatty and connect your MCP client. You also need the API base URL, one documented endpoint, its inputs, expected response, and supported authentication.

Start with one useful read

Choose a GET operation that confirms access to the API. Give the agent the provider's documentation and a specific task. Ask for the smallest OpenAPI document that covers that operation, including the server URL, parameters, and response.

Using this API documentation: <documentation URL or excerpt>
Write a minimal OpenAPI 3 document for the GET operation that reads <resource>.
Include the required inputs and response. Show me the document before import.

The connected agent supplies the interpretation and schema authorship. Compare its method, path, inputs, and server URL with the provider documentation before executing a call.

Validate and preview the document

In the inspected source, catalog_validate_openapi, catalog_preview_import, and catalog_import_openapi accept the full JSON or YAML text in source. Set source_type to inline. The document does not need a temporary file in that implementation.

{
  "source": "<complete OpenAPI JSON or YAML document>",
  "source_type": "inline"
}

Have the agent validate the document, then preview the import with a catalog title. Check that the preview contains the expected command and base URL. Fix schema errors in the document and repeat validation before importing.

Import and run the operation

Ask the agent to import the validated document with catalog_import_openapi. Then use search_commands and get_command to find the exact generated command and required inputs. Run the GET operation with run_safe_command and inspect the API response.

Open the TUI, search for that command, complete its inputs through autocomplete, and run it yourself. If the response differs from the documentation, inspect the generated command and the API response before changing the catalog.