AI Providers CSV Import/Export API

This document describes the CSV import and export functionality for AI providers in the Veriprompt AI Gateway platform.

Overview

The AI Provider CSV functionality allows administrators to:

Import multiple AI providers from CSV files with validation and optional API testing
Export existing AI providers to CSV format with filtering options
Manage provider types including LLMs, SLMs, Agents, and specialized AI services

Provider Types

Veriprompt supports the following AI provider types:

Large Language Models (LLMs)

LLM_FOUNDATION - Foundation models (GPT-4, Claude, Gemini)
LLM_FINE_TUNED - Fine-tuned versions of foundation models
LLM_CODE - Specialized for code generation (Codex, CodeLlama)
LLM_MULTIMODAL - Vision + text capabilities (GPT-4V, Claude 3)

Small Language Models (SLMs)

SLM_CHAT - Small chat models (Phi, Gemma)
SLM_EMBEDDING - Embedding models (text-embedding-ada-002)
SLM_CLASSIFICATION - Classification/sentiment models
SLM_SUMMARIZATION - Specialized summarization models

Autonomous Agents

AGENT_REASONING - Models with reasoning/planning (o1, Claude reasoning)
AGENT_TOOL_USE - Function calling and tool use specialists
AGENT_WORKFLOW - Multi-step workflow execution
AGENT_MEMORY - Agents with persistent memory

Specialized AI Services

SPEECH_TO_TEXT - Whisper, Azure Speech, etc.
TEXT_TO_SPEECH - ElevenLabs, Azure TTS, etc.
IMAGE_GENERATION - DALL-E, Midjourney, Stable Diffusion
IMAGE_ANALYSIS - Vision models, OCR services

Custom & Research

RESEARCH_MODEL - Experimental/research models
CUSTOM_ENDPOINT - Custom API endpoints
HYBRID_PIPELINE - Multi-model pipelines

CSV Import API

Endpoint

POST /api/admin/ai-providers/import

Authentication

Requires admin-level authentication (SUPER_ADMIN, ACCOUNT_OWNER, or ADMIN role).

Request Format

Content-Type: application/json

json

{
  "csvData": "string (required)",
  "testApiConnections": "boolean (optional, default: false)",
  "skipDuplicates": "boolean (optional, default: true)",
  "updateExisting": "boolean (optional, default: false)"
}

CSV Format

The CSV must include the following columns (headers required):

csv

Provider Name,Type,Model,Comment,API Gateway URL,API Key,Active Status,Country,Compliance Memberships,Network Location
OpenAI GPT-4,LLM_FOUNDATION,gpt-4o,Production model for general tasks,https://api.openai.com/v1,sk-proj-abc123...,active,US,"US;EUGDPR","us-east-1"
Anthropic Claude,LLM_FOUNDATION,claude-3-5-sonnet-20241022,Advanced reasoning model,https://api.anthropic.com,sk-ant-xyz789...,active,US,"US;EUGDPR","us-west-2"
Local Llama,SLM_CHAT,llama-3.1-8b-instruct,Local deployment for privacy,http://localhost:8080/v1,local-key-123,passive,DE,"EU;EUGDPR","on-prem-berlin"
Whisper STT,SPEECH_TO_TEXT,whisper-1,Speech to text service,https://api.openai.com/v1,sk-proj-def456...,active,US,"US","edge-cdn"

Column Descriptions

Column	Required	Description	Example
Provider Name	Yes	Unique name for the provider	`OpenAI GPT-4`
Type	Yes	Provider type from enum	`LLM_FOUNDATION`
Model	Yes	Primary model name	`gpt-4o`
Comment	No	Description or notes	`Production model`
API Gateway URL	Yes	Full API endpoint URL	`https://api.openai.com/v1`
API Key	Yes	API authentication key	`sk-proj-abc123...`
Active Status	Yes	`active`/`passive` or `ACTIVE`/`INACTIVE`	`active`
Country	Yes	ISO country code (upper-case)	`US`
Compliance Memberships	No	Semicolon-separated memberships	`EU;EUGDPR;USFEDRAMP`
Network Location	No	Datacenter/region label	`eu-central-1`
Keywords	No	Legacy free-text keywords (not used for routing decisions)	`legal,coding,medical`
Specializations	No	Canonical specialization codes for smart routing; aliases like `code` or `security` resolve automatically, unknown terms are reported in `specializationWarnings`, a blank cell keeps the existing value	`coding,cybersecurity`
Provider Params (JSON)	No	JSON config for parameter overrides	`{"maxTokensCap":4096}`

Provider Params

The Provider Params column accepts a JSON object that configures how VeriPrompt translates API parameters for this specific model. See Provider Params Reference for the full schema and examples.

API Testing

When testApiConnections is set to true, the system will:

OpenAI/Compatible APIs: Test /models endpoint
Anthropic APIs: Test /messages endpoint with minimal request
Generic APIs: Test basic connectivity to provided endpoint

Test results include:

Connection success/failure
Response time in milliseconds
Error details if connection fails

Response Format

json

{
  "success": true,
  "result": {
    "success": true,
    "imported": 3,
    "skipped": 1,
    "errors": [
      {
        "row": 5,
        "error": "Invalid provider type",
        "data": { "providerName": "Invalid Provider" }
      }
    ],
    "apiTestResults": [
      {
        "providerName": "OpenAI GPT-4",
        "testPassed": true,
        "responseTime": 245
      },
      {
        "providerName": "Invalid API",
        "testPassed": false,
        "responseTime": 5000,
        "error": "HTTP 401: Unauthorized"
      }
    ]
  }
}

Example Usage

javascript

// Import CSV with API testing
const csvData = `Provider Name,Type,Model,Comment,API Gateway URL,API Key,Active Status
OpenAI GPT-4,LLM_FOUNDATION,gpt-4o,Production model,https://api.openai.com/v1,sk-proj-abc123,active
Claude Sonnet,LLM_FOUNDATION,claude-3-5-sonnet-20241022,Advanced reasoning,https://api.anthropic.com,sk-ant-xyz789,active`;

const response = await fetch('/api/admin/ai-providers/import', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    csvData: csvData,
    testApiConnections: true,
    skipDuplicates: true,
    updateExisting: false
  })
});

const result = await response.json();
console.log(`Imported: ${result.result.imported}, Errors: ${result.result.errors.length}`);

CSV Export API

Endpoint

GET /api/admin/ai-providers/export
POST /api/admin/ai-providers/export

Authentication

Requires admin-level authentication (SUPER_ADMIN, ACCOUNT_OWNER, or ADMIN role).

GET Method - Simple Export

Query Parameters

Parameter	Type	Default	Description
`format`	string	`csv`	Export format: `csv` or `json`
`status`	string	`all`	Filter by status: `ACTIVE`, `INACTIVE`, `MAINTENANCE`, `all`
`type`	string	-	Filter by provider type (e.g., `LLM_FOUNDATION`)
`includeInactive`	boolean	`true`	Include inactive providers
`limit`	number	-	Maximum number of providers to export (1-1000)
`search`	string	-	Search in provider names or models

Example GET Requests

bash

# Export all active providers as CSV
GET /api/admin/ai-providers/export?status=ACTIVE&format=csv

# Export LLM foundation models as JSON
GET /api/admin/ai-providers/export?type=LLM_FOUNDATION&format=json

# Search and export providers containing "openai"
GET /api/admin/ai-providers/export?search=openai&limit=50

POST Method - Advanced Export

For complex filtering, use the POST method:

json

{
  "format": "csv",
  "filters": {
    "status": "ACTIVE",
    "type": "LLM_FOUNDATION",
    "search": "gpt",
    "createdAfter": "2024-01-01T00:00:00Z",
    "createdBefore": "2024-12-31T23:59:59Z",
    "limit": 100
  },
  "specificProviderIds": ["provider-id-1", "provider-id-2"]
}

Security Note

API keys in exports are masked - only the last 10 characters are shown:

Original: sk-proj-abc123def456ghi789jkl
Exported: ...ghi789jkl

Response Formats

CSV Response

csv

# AI Providers Export for Company Name
# Generated: 2024-01-15T10:30:00.000Z
# Total Providers: 5
# Filters Applied: Status=ACTIVE, Type=all, Include Inactive=true
# Search Query: none
# Note: API keys are masked showing only last 10 characters

Provider Name,Type,Model,Comment,API Gateway URL,API Key,Active Status,Created At,Last Health Check,Success Rate
"OpenAI GPT-4","LLM_FOUNDATION","gpt-4o","Created: 1/10/2024, Response Time: 250ms","https://api.openai.com/v1","...abc123def","active","2024-01-10T14:30:00.000Z","2024-01-15T10:25:00.000Z","0.98"

JSON Response

json

{
  "success": true,
  "count": 5,
  "data": [
    {
      "providerName": "OpenAI GPT-4",
      "type": "LLM_FOUNDATION",
      "model": "gpt-4o",
      "comment": "Created: 1/10/2024, Response Time: 250ms",
      "apiGatewayUrl": "https://api.openai.com/v1",
      "apiKey": "...abc123def",
      "activeStatus": "active",
      "createdAt": "2024-01-10T14:30:00.000Z",
      "lastHealthCheck": "2024-01-15T10:25:00.000Z",
      "successRate": 0.98
    }
  ],
  "exportedAt": "2024-01-15T10:30:00.000Z",
  "filters": {
    "status": "all",
    "type": null,
    "includeInactive": true,
    "search": null,
    "limit": null
  }
}

Error Handling

Common Error Responses

400 - Bad Request

json

{
  "error": "Invalid request data",
  "details": [
    {
      "path": ["csvData"],
      "message": "CSV data is required"
    }
  ]
}

401 - Unauthorized

json

{
  "error": "Unauthorized"
}

403 - Forbidden

json

{
  "error": "Insufficient permissions"
}

500 - Server Error

json

{
  "error": "Failed to import AI providers"
}

Import-Specific Errors

Invalid CSV format: Missing headers, wrong number of columns
Validation errors: Invalid provider type, malformed URLs, empty required fields
Duplicate providers: When skipDuplicates is false and provider exists
API test failures: When testApiConnections is true and connections fail

Rate Limits

Import operations: 5 requests per minute per company
Export operations: 10 requests per minute per company
Maximum CSV size: 1MB (approximately 5,000 providers)
Maximum providers per import: 1,000 rows

Best Practices

Import Best Practices

Test with small batches first (10-20 providers)
Enable API testing for production imports
Use skipDuplicates: true to avoid errors on re-imports
Validate CSV format before uploading:
- Ensure all required columns are present
- Check provider type values against enum
- Verify API gateway URLs are valid

Export Best Practices

Use filtering to export only needed providers
Choose appropriate format:
- CSV for spreadsheet editing
- JSON for programmatic processing
Consider data sensitivity - API keys are masked but other data is not

Security Best Practices

Rotate API keys after sharing exported data
Limit export access to necessary administrators only
Use HTTPS for all API communications
Audit exports - all operations are logged

Audit Logging

All import and export operations are logged with:

User who performed the operation
Timestamp
Number of providers affected
Filters applied (for exports)
Success/failure status

Audit logs can be viewed in the admin dashboard under "Audit Trail".

Integration Examples

JavaScript/TypeScript

typescript

interface ImportRequest {
  csvData: string;
  testApiConnections?: boolean;
  skipDuplicates?: boolean;
  updateExisting?: boolean;
}

class AIProviderImporter {
  async importFromCSV(data: ImportRequest): Promise<ImportResult> {
    const response = await fetch('/api/admin/ai-providers/import', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    
    if (!response.ok) {
      throw new Error(`Import failed: ${response.statusText}`);
    }
    
    return await response.json();
  }

  async exportToCSV(filters?: ExportFilters): Promise<string> {
    const params = new URLSearchParams();
    if (filters?.status) params.append('status', filters.status);
    if (filters?.type) params.append('type', filters.type);
    if (filters?.search) params.append('search', filters.search);
    
    const response = await fetch(`/api/admin/ai-providers/export?${params}`);
    return await response.text();
  }
}

Python

python

import requests
import csv
from typing import Dict, List, Optional

class AIProviderManager:
    def __init__(self, base_url: str, api_token: str):
        self.base_url = base_url
        self.headers = {"Authorization": f"Bearer {api_token}"}
    
    def import_providers(self, csv_data: str, test_apis: bool = False) -> Dict:
        """Import AI providers from CSV data"""
        payload = {
            "csvData": csv_data,
            "testApiConnections": test_apis,
            "skipDuplicates": True
        }
        
        response = requests.post(
            f"{self.base_url}/api/admin/ai-providers/import",
            json=payload,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()
    
    def export_providers(self, format: str = "csv", **filters) -> str:
        """Export AI providers with optional filtering"""
        params = {"format": format, **filters}
        
        response = requests.get(
            f"{self.base_url}/api/admin/ai-providers/export",
            params=params,
            headers=self.headers
        )
        response.raise_for_status()
        return response.text

Changelog

Version 1.0.0 - 2024-01-15

Initial release of CSV import/export functionality
Support for all provider types (LLM, SLM, Agent, Specialized)
API testing during import
Flexible export filtering
Security: API key masking in exports
Comprehensive error handling and validation

AI Providers CSV Import/Export API ​

Overview ​

Provider Types ​

Large Language Models (LLMs) ​

Small Language Models (SLMs) ​

Autonomous Agents ​

Specialized AI Services ​

Custom & Research ​

CSV Import API ​

Endpoint ​

Authentication ​

Request Format ​

CSV Format ​

Column Descriptions ​

API Testing ​

Response Format ​

Example Usage ​

CSV Export API ​

Endpoint ​

Authentication ​

GET Method - Simple Export ​

Query Parameters ​

Example GET Requests ​

POST Method - Advanced Export ​

Security Note ​

Response Formats ​

CSV Response ​

JSON Response ​

Error Handling ​

Common Error Responses ​

400 - Bad Request ​

401 - Unauthorized ​

403 - Forbidden ​

500 - Server Error ​

Import-Specific Errors ​

Rate Limits ​

Best Practices ​

Import Best Practices ​

Export Best Practices ​

Security Best Practices ​

Audit Logging ​

Integration Examples ​

JavaScript/TypeScript ​

Python ​

Changelog ​

Version 1.0.0 - 2024-01-15 ​

AI Providers CSV Import/Export API

Overview

Provider Types

Large Language Models (LLMs)

Small Language Models (SLMs)

Autonomous Agents

Specialized AI Services

Custom & Research

CSV Import API

Endpoint

Authentication

Request Format

CSV Format

Column Descriptions

API Testing

Response Format

Example Usage

CSV Export API

Endpoint

Authentication

GET Method - Simple Export

Query Parameters

Example GET Requests

POST Method - Advanced Export

Security Note

Response Formats

CSV Response

JSON Response

Error Handling

Common Error Responses

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Server Error

Import-Specific Errors

Rate Limits

Best Practices

Import Best Practices

Export Best Practices

Security Best Practices

Audit Logging

Integration Examples

JavaScript/TypeScript

Python

Changelog

Version 1.0.0 - 2024-01-15