OpenAPI Connector

Connect Zenmako to any REST API that has an OpenAPI (Swagger) specification. This generic connector enables AI to interact with your internal APIs, third-party services, or any system that publishes an OpenAPI spec - without requiring a dedicated connector.

Overview

The OpenAPI connector is a universal adapter that reads an OpenAPI specification and automatically generates tools for each endpoint. This means you can connect virtually any modern API to Zenmako, including:

  • Your company's internal microservices
  • Third-party APIs without dedicated Zenmako connectors
  • Custom integrations with vendor systems
  • Any REST API with OpenAPI 2.0 (Swagger) or OpenAPI 3.x documentation

    • What You Need

    Before connecting an API via OpenAPI, gather the following:

    OpenAPI Specification

    You need access to the API's OpenAPI specification in one of these formats:

  • URL: A direct link to the JSON or YAML spec (e.g., https://api.example.com/openapi.json)
  • File content: The raw JSON or YAML specification content

    • Most modern APIs publish their OpenAPI spec at a standard location like /openapi.json, /swagger.json, /api-docs, or in their developer documentation.

    Authentication Credentials

    Depending on how the API authenticates requests, you will need one of:

    Auth TypeWhat You Need
    API KeyThe API key value and header name (e.g., X-API-Key, Authorization)
    Bearer TokenAn access token or JWT to include in the Authorization header
    Basic AuthUsername and password
    NoneSome APIs are public and require no authentication

    The connector extracts authentication requirements from the OpenAPI spec's securitySchemes (OpenAPI 3.x) or securityDefinitions (Swagger 2.0) section.

    Connecting an API

  • Navigate to the Connections page in Zenmako
  • Click Add Connection and select OpenAPI
  • Enter the connection details:
    • - Spec URL or Content: Paste the URL to your OpenAPI spec, or the raw JSON/YAML content - API Key (if applicable): Your API key for authentication - Base URL (optional): Override the base URL from the spec if needed (useful for staging/production environments)
  • Click Save
  • Click Test Connection to verify the setup

    • If the test succeeds, Zenmako has parsed your OpenAPI spec and the connector is ready to use.

    How It Works

    When you connect an API using the OpenAPI connector, Zenmako:

  • Parses the specification - Fetches and validates your OpenAPI spec (supports both JSON and YAML formats)
  • Extracts the base URL - Determines the API's server URL from the spec's servers array (OpenAPI 3.x) or host/basePath fields (Swagger 2.0)
  • Identifies authentication - Reads security schemes from the spec and configures credential handling accordingly
  • Generates tools - Creates a tool for each operation (endpoint + HTTP method) defined in the spec, including:
    • - Path parameters (e.g., /users/{userId}) - Query parameters - Request body schemas - Response type information
  • Enables AI access - Your AI agents can now discover and call these tools to interact with the API

    • Available Actions

    The actions available depend entirely on the API you connect. The connector generates tools based on the paths and operations defined in the OpenAPI spec. Common patterns include:

    PatternGenerated Tool Description
    GET /usersList or search users
    GET /users/{id}Get a specific user by ID
    POST /usersCreate a new user
    PUT /users/{id}Update an existing user
    DELETE /users/{id}Delete a user

    Example Use Cases

    Connect Your Internal API

    If your team has built an internal service with OpenAPI documentation:

  • Get the spec URL from your development team (e.g., https://internal-api.yourcompany.com/swagger.json)
  • Add it as an OpenAPI connection with your internal API key
  • AI can now query and interact with your internal systems

    • Connect a Third-Party API

    For services without a dedicated Zenmako connector:

  • Find the API's OpenAPI specification in their developer docs
  • Generate or obtain API credentials from the service provider
  • Connect using the OpenAPI connector
  • Enable AI-powered automation for that service

    • Example: Pet Store API

    Using the classic Petstore demo API:

  • Spec URL: https://petstore.swagger.io/v2/swagger.json
  • Auth: API key in header api_key

    • Once connected, prompts like these would work:

  • "List all available pets"
  • "Find pets by status 'available'"
  • "Get details for pet ID 12345"

    • Common Issues

    "Failed to parse OpenAPI specification"

    This error occurs when the spec cannot be loaded or parsed. Solutions:

  • Verify the spec URL is accessible (try opening it in a browser)
  • Check that the spec is valid OpenAPI 2.0 or 3.x format
  • Ensure the URL returns JSON or YAML content, not an HTML documentation page
  • If pasting content directly, verify it is properly formatted JSON or YAML

    • "Authentication failed" or "401 Unauthorized"

    The API rejected your credentials. Solutions:

  • Verify your API key or token is correct and not expired
  • Check that you're using the correct authentication header name (some APIs use X-API-Key, others use Authorization, etc.)
  • Ensure your credentials have access to the endpoints you're trying to use
  • For Bearer tokens, make sure the token format is correct (some APIs require Bearer prefix, others don't)

    • "Tool not found" or missing endpoints

    Some endpoints from the spec aren't appearing as tools. Solutions:

  • The spec may define operations that aren't suitable for tool generation
  • Check if the endpoint requires authentication that wasn't configured
  • Some legacy Swagger 2.0 specs may have compatibility limitations
  • Operations without proper operationId or descriptions may be skipped