# Creating API Connections

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

## Prerequisites

Before creating an API Connection, 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 Connections 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 connections
2. **Remove Unnecessary Content**: Strip out verbose descriptions, examples, and documentation that aren’t essential
3. **Focus on Core Endpoints**: Create connections for your most critical API operations

## Step 2: Access the Vendia Console

1. Log in to the [Vendia console](https://www.vendia.com/)
2. Navigate to your MCP Server dashboard
3. Select **API Connections** from the navigation menu

## Step 3: Create a New API Connection

1. Click the **Add API Connection** 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 Connection
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 Connection

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 Connections** with **25 operations per catalog**. To use more connections 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 connection 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

- **[Authentication and Headers](https://docs.vendia.com/platform/vendia-mcp-server/api-connections/authentication)** - Learn more about authentication options
- **[Best Practices](https://docs.vendia.com/platform/vendia-mcp-server/api-connections/best-practices)** - Optimize your API Connections
- **[Use Cases](https://docs.vendia.com/platform/vendia-mcp-server/api-connections/use-cases)** - See examples of API Connections in action
- **[Troubleshooting](https://docs.vendia.com/platform/vendia-mcp-server/api-connections/troubleshooting)** - Resolve common issues