API Catalogs

API Catalogs enable AI applications to discover and interact with your APIs by adding OpenAPI or Swagger specification files. Instead of manually describing API endpoints to AI agents or building custom integrations, simply add your API specification and give AI agents the ability to understand and call your APIs — whether they’re internal or external APIs, or third-party integrations.

With API Catalogs, you unlock powerful AI-driven API workflows while maintaining control over which APIs are exposed, how they are accessed, and who can use them:

• Leverage Existing Specifications: AI agents work directly with your OpenAPI/Swagger specifications — no need to rewrite or translate your API documentation
• Enable API Discovery: AI applications can explore available endpoints, understand parameters, and make informed API calls
• Simplify Integration: Add once and let AI agents handle the complexity of API interactions
• Support Multiple APIs: Add multiple API specifications to give AI agents access to diverse services

Use Cases

API Catalogs enable a wide range of AI-driven workflows:

• AI Workflow Automation: AI agents can orchestrate multi-step workflows across internal or external APIs
• Internal Service Integration: Give AI agents access to your internal microservices and APIs
• Third-Party API Discovery: Enable AI to explore and use external APIs like Slack, JIRA, or Snowflake
• Automated Testing: Let AI agents generate and execute API test cases based on specifications
• API Documentation: AI can answer questions about API capabilities by reading the specification

Getting Started

1. Prepare Your API Specification: Ensure you have a valid OpenAPI or Swagger specification file in JSON, YAML, or YML format
2. Add to Vendia: Use the Vendia console to create a new API Catalog entry
3. Configure Settings: Set optional parameters like base URL override, version override, custom headers, and description
4. Save the Catalog: Catalogs are automatically enabled when saved
5. Use with AI Applications: AI agents can now discover and interact with your APIs through MCP-compatible applications

Supported Specification Formats

API Catalogs support the following specification formats:

Format	Extensions	Description
JSON	.json	OpenAPI/Swagger specifications in JSON format
YAML	.yaml, .yml	OpenAPI/Swagger specifications in YAML format

Specification Versions

API Catalogs support both OpenAPI 3.x and Swagger 2.0 specifications. Ensure your specification file is valid before adding it. In the Free Tier, each API catalog is limited to 25 operations (API endpoints defined in your specification, such as GET /users, POST /orders, etc.).

Configuration Options

When creating an API Catalog, you can configure the following settings:

Required Fields

• API Name: A unique identifier for your API (e.g., “Snowflake”, “slack”, “JIRA”)
• OpenAPI/Swagger File: The specification file to add in JSON, YAML, or YML format (max file size: 5MB)

Optional Fields

• Description: A brief description of the API and its purpose (max 500 characters)
• Base URL Override: Override the base URL from the specification (e.g., https://api.example.com)
• Version Override: Override the version from the specification using numeric semantic versioning format (e.g., 1.0.0, 2.1.3, 3.0.0)
• Headers: Add custom headers to include in API requests, such as authentication tokens or API keys

Custom Headers

Headers are useful for including authentication credentials like API keys, bearer tokens, or other custom headers required by your API. Add headers as key-value pairs.

Managing API Catalogs

Creating an API Catalog

1. Navigate to File Sharing → API Catalogs in the Vendia console
2. Click “Add API Catalog” in the upper right
3. Enter the required API Name
4. Upload your OpenAPI/Swagger specification file
5. Optionally configure:
   • Description
   • Base URL Override
   • Version Override (semantic versioning: MAJOR.MINOR.PATCH)
   • Custom headers for authentication
6. Click “Upload API Specification” to create the catalog (automatically enabled)

Enabling and Disabling Catalogs

Toggle the Enabled switch for each API Catalog to control whether it’s available to AI applications. Disabled catalogs are not accessible to AI agents.

Updating API Catalogs

To update an API Catalog, you can use either of these methods:

Option 1: Click the API catalog name

1. Click on the API catalog name in the list to open the edit view
2. Make your changes to settings or upload a new specification file
3. Click Save Changes

Option 2: Use the Actions menu

1. Click the Actions menu (three dots) for the catalog you want to modify
2. Select “Edit” to open the edit view
3. Make your changes and click Save Changes

Downloading Specification Files

To download the specification file for an API Catalog, click on the file name (e.g., openapi.json, swagger.yaml) shown in the catalog details.

Deleting API Catalogs

To remove an API Catalog:

1. Click the Actions menu (three dots) for the catalog you want to delete
2. Select “Delete”
3. Confirm the deletion

Deletion Impact

Deleting an API Catalog immediately removes it from AI applications. Any AI agents currently using the catalog will lose access.

Prerequisites

Before creating your first API Catalog, ensure you have:

1. Valid API Specification: An OpenAPI or Swagger specification file in JSON, YAML, or YML format
2. API Access: If the API requires authentication, have your API keys or tokens ready
3. Vendia Account: Access to the Vendia Free Tier or Enterprise Tier console

File Size and Limits

All Tiers

• Maximum Specification File Size: 5MB per specification file
• Supported Formats: JSON, YAML, YML

Free Tier Limits

• Maximum API Catalogs: Up to 2 API Catalog entries
• Operations per Catalog: Maximum 25 operations per API catalog
• MCP Calls: Up to 100,000 MCP calls per month (shared across all resources)
• Concurrent Requests: Maximum of 2 concurrent requests

Optimizing Large Specifications

If your specification file exceeds 5MB (all tiers), compress it by removing unnecessary documentation and examples. If your API specification contains more than 25 operations (Free Tier), upgrade to Vendia Pro or Enterprise for higher limits.

Security Considerations

Authentication

API Catalogs do not automatically handle authentication. You have several options:

1. Custom Headers: Add API keys, bearer tokens, or other authentication headers in the catalog configuration
2. OAuth/JWT: If your API uses OAuth or JWT, configure the appropriate headers
3. Public APIs: For public APIs without authentication, no additional configuration is needed

Credential Security

Be cautious when adding authentication credentials to headers. Ensure your Vendia account is secure and consider using short-lived tokens or API keys with limited scope.

Need Help?

If you encounter issues during setup or have questions about using API Catalogs:

Free Tier Support

• Review the MCP Free Tier FAQ for Free Tier-specific questions
• Submit questions via our contact form (online support only)

Enterprise Tier Support

• Review our MCP Server FAQ for common questions
• Contact Vendia Support for technical assistance

Additional Resources

For more information about configuring and using API Catalogs:

• Creating API Catalogs - Step-by-step guide to adding your first catalog
• Authentication and Headers - Configure secure API access
• Best Practices - Optimize your API catalog configurations
• Use Cases - Real-world examples and implementations
• Troubleshooting - Common issues and solutions

For more information about Vendia MCP Server:

• MCP Server Overview - Learn about available tools and capabilities
• Getting Started Guide - Step-by-step setup instructions for AI applications
• Storage Connections - Configure access to external Amazon S3 buckets
• MCP Server FAQ - Technical questions and answers