Skip to content
Vendia

Creating API Catalogs

This guide walks you through creating API Catalogs in Vendia MCP Server to enable AI applications to discover and interact with your APIs.

Prerequisites

Before creating an API Catalog, ensure you have:

  • A valid OpenAPI or Swagger specification file (JSON, YAML, or YML format)
  • Access to the Vendia console
  • Your API’s base URL (if different from the specification)
  • Authentication credentials for your API (API key, bearer token, etc.)

Step 1: Prepare Your API Specification

Supported Formats

API Catalogs support the following specification formats:

  • OpenAPI 3.x (JSON or YAML)
  • Swagger 2.0 (JSON or YAML)

File Size Limits

  • Maximum file size: 5MB (all tiers)
  • Maximum operations per catalog: 25 operations (API endpoints like GET /users, POST /orders, etc.) - Free Tier only

Optimize Your Specification

If your specification exceeds these limits:

  1. Split Large Specifications: Divide your API into multiple smaller catalogs
  2. Remove Unnecessary Content: Strip out verbose descriptions, examples, and documentation that aren’t essential
  3. Focus on Core Endpoints: Create catalogs for your most critical API operations

Step 2: Access the Vendia Console

  1. Log in to the Vendia console
  2. Navigate to your MCP Server dashboard
  3. Select API Catalogs from the navigation menu

Step 3: Create a New API Catalog

  1. Click the Add API Catalog button
  2. Provide a name for your catalog (this will be visible to AI applications)
  3. Add an optional description to help identify the catalog’s purpose

Step 4: Upload Your Specification

  1. Click Choose File or drag and drop your specification file
  2. Supported formats: .json, .yaml, .yml
  3. Wait for the file to upload and validate

Step 5: Configure API Settings

Base URL (Optional)

If your API’s base URL differs from the one in your specification:

  1. Enter the Base URL Override field
  2. Example: https://api.example.com/v1

This is useful when:

  • Using different environments (staging vs. production)
  • The specification has a generic placeholder URL
  • You want to test against a specific API instance

Version (Optional)

If your API’s version differs from the one in your specification:

  1. Enter the Version Override field using numeric semantic versioning format
  2. Example: 1.0.0, 2.1.3, 3.0.0

Only numeric versions are supported: MAJOR.MINOR.PATCH (e.g., 1.0.0). Pre-release labels like -beta or -alpha are not supported.

Step 6: Add Authentication (Optional)

If your API requires authentication, you can add custom headers:

Adding Headers

  1. Click Add Header
  2. Enter the Header Name (e.g., Authorization, X-API-Key)
  3. Enter the Header Value (e.g., Bearer YOUR_TOKEN, your API key)

Common Authentication Patterns

API Key in Header:

Header Name: X-API-Key
Header Value: your-api-key-here

Bearer Token:

Header Name: Authorization
Header Value: Bearer your-token-here

Basic Auth:

Header Name: Authorization
Header Value: Basic base64-encoded-credentials

Security Best Practices

Step 7: Save the Catalog

  1. Click Upload API Specification to create the API Catalog
  2. The catalog is automatically enabled when saved
  3. AI applications can now discover and interact with your API
  4. You can disable the catalog later by toggling the Enable switch to temporarily restrict access

Verifying Your API Catalog

After saving the catalog:

  1. Check the Status: Ensure the catalog shows as “Active” or “Enabled”
  2. Review Operations: Verify that the expected API operations are listed
  3. Test with AI: Connect an AI application and ask it to describe the available endpoints
  4. Verify Authentication: If using authentication, test that API calls succeed

Free Tier Catalog Limits

The Free Tier supports up to 2 API Catalogs with 25 operations per catalog. To use more catalogs or operations, upgrade to Vendia Pro or Enterprise.

Troubleshooting

Specification Upload Fails

Problem: The specification file won’t upload or shows validation errors.

Solutions:

  • Verify the file is valid JSON or YAML
  • Check that the file size is under 5MB
  • Ensure the specification follows OpenAPI 3.x or Swagger 2.0 standards
  • Use an online validator to check your specification

Authentication Not Working

Problem: API calls fail with authentication errors.

Solutions:

  • Verify the header name matches your API’s requirements (case-sensitive)
  • Check that the token or API key is valid and not expired
  • Ensure the authentication credential has the necessary permissions
  • Test the API directly (outside of Vendia) to confirm the credentials work

Catalog Not Visible to AI

Problem: AI application can’t see or access the catalog.

Solutions:

  • Verify the catalog is enabled (toggle is on)
  • Check that your MCP server URL is correctly configured in the AI application
  • Restart your AI application after adding the catalog
  • Review the MCP server logs for connection errors

Next Steps