Managing Connections

This guide covers how to view, update, and troubleshoot your connections after they've been created.

Viewing Connections

Web Interface

1. Log in to LangMart
2. Navigate to Connections in the sidebar
3. You'll see a list of all your connections with:
   • Provider name and icon
   • Connection status (active, inactive, error)
   • Gateway type (Cloud or Self-Hosted)
   • Scope (Individual or Organization)
   • Number of available models
   • Last health check time

API

# List all connections
curl https://api.langmart.ai/api/connections \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY"

Response:

{
  "connections": [
    {
      "id": "conn-abc123",
      "provider": {
        "id": "prov-123",
        "key": "openai",
        "name": "OpenAI"
      },
      "endpoint_url": "https://api.openai.com/v1",
      "gateway_type": 2,
      "status": "active",
      "scope": "individual",
      "model_count": 42,
      "rate_limits": {
        "rpm": 60,
        "tpm": 40000
      },
      "created_at": "2025-01-08T10:30:00Z"
    }
  ]
}

Filtering Connections

Filter by provider, gateway type, or status:

# Filter by provider
curl "https://api.langmart.ai/api/connections?provider_id=PROVIDER_UUID" \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY"

# Filter by gateway type
curl "https://api.langmart.ai/api/connections?gateway_type=2" \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY"

# Filter by status
curl "https://api.langmart.ai/api/connections?status=active" \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY"

# Filter by scope
curl "https://api.langmart.ai/api/connections?scope=organization" \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY"

Updating API Keys

API keys can be rotated without deleting and recreating the connection.

Web Interface

1. Find your connection in the list
2. Click the menu icon (three dots)
3. Select Update API Key
4. Paste your new API key
5. Click Update

API

curl -X POST https://api.langmart.ai/api/connections/CONN_ID/update-key \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk-new-api-key-here"
  }'

Response:

{
  "success": true,
  "message": "API key updated successfully"
}

Important: After updating the API key, test the connection to verify it works.

Enabling and Disabling Connections

Disable a Connection

Disabling a connection prevents it from being used for inference without deleting it.

curl -X PUT https://api.langmart.ai/api/connections/CONN_ID \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactive"
  }'

Enable a Connection

curl -X PUT https://api.langmart.ai/api/connections/CONN_ID \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active"
  }'

Connection Health Checks

LangMart periodically checks connection health. You can also trigger manual health checks.

Manual Health Check

curl -X POST https://api.langmart.ai/api/connections/CONN_ID/test \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY"

Health Status Values

Automatic Recovery

When a connection test passes after being in an error state:

• Connection status is updated to active
• Associated models are re-enabled
• Health check metadata is updated

Updating Rate Limits

Adjust rate limits to match your provider tier:

curl -X PUT https://api.langmart.ai/api/connections/CONN_ID \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_limit_rpm": 120,
    "rate_limit_tpm": 80000
  }'

Model Resolution Priority

Control which connection is used when multiple connections provide the same model.

Prefer Score

Higher scores are tried first. Default is 100.

curl -X PUT https://api.langmart.ai/api/connections/CONN_ID \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prefer_score": 200
  }'

Use cases:

• Set your fastest connection to prefer_score: 200
• Set your backup connection to prefer_score: 50
• Primary connection handles most traffic; backup kicks in on failures

Allow Fallback

When enabled, if this connection fails, LangMart tries other connections.

curl -X PUT https://api.langmart.ai/api/connections/CONN_ID \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_fallback": true
  }'

Disable fallback if you want strict routing to specific connections:

{
  "allow_fallback": false
}

Deleting Connections

Web Interface

1. Find your connection in the list
2. Click the menu icon (three dots)
3. Select Delete
4. Confirm the deletion

API

curl -X DELETE https://api.langmart.ai/api/connections/CONN_ID \
  -H "Authorization: Bearer YOUR_LANGMART_API_KEY"

Warning: Deleting a connection also removes all associated models. Consider disabling instead if you might need it again.

Troubleshooting Connection Issues

Connection Shows "Error" Status

Symptoms:

• Red error indicator
• Models not available
• API requests fail

Solutions:

1. Test the connection manually
2. Verify your API key is still valid with the provider
3. Check if the provider has any outages
4. Review rate limit settings

"Authentication Failed"

Causes:

• API key has been revoked or expired
• API key was entered incorrectly
• Provider account has billing issues

Solutions:

1. Log into your provider account
2. Generate a new API key
3. Update the connection with the new key
4. Test the connection

"Rate Limit Exceeded"

Causes:

• Exceeded provider's rate limits
• Too many concurrent requests
• LangMart rate limits set higher than provider allows

Solutions:

1. Wait for the rate limit window to reset
2. Lower your rate limit settings in LangMart
3. Upgrade your provider tier
4. Add multiple connections for load balancing

"Connection Refused"

Causes:

• Incorrect endpoint URL
• Provider API is down
• Network/firewall issues

Solutions:

1. Verify the endpoint URL matches the provider's documentation
2. Check the provider's status page
3. Try accessing the provider API directly
4. Check for firewall or proxy issues

Models Not Appearing

Causes:

• Discovery hasn't been run
• API key lacks list models permission
• Connection is in error state

Solutions:

1. Run model discovery manually
2. Check API key permissions with provider
3. Test and fix the connection first
4. Some providers don't support model listing - create models manually

Self-Hosted Gateway Issues

Causes:

• Gateway service not running
• Gateway not connected to LangMart
• Network connectivity issues

Solutions:

1. Check gateway logs: tail -f /tmp/gw3.log
2. Verify gateway is running: ./core.sh status
3. Restart the gateway: ./core.sh restart 3
4. Check WebSocket connection status

Connection Best Practices

1. Use Descriptive Names

Give connections clear names so you can identify them later:

• "OpenAI Production" vs "OpenAI Testing"
• "Anthropic - Team Project"

2. Set Appropriate Rate Limits

Match your rate limits to your provider tier to avoid unnecessary errors:

3. Enable Fallback for Production

For production workloads, keep allow_fallback: true so requests don't fail completely if one connection has issues.

4. Use Organization Connections for Teams

If your team shares API access, create organization connections instead of individual ones. This:

• Centralizes billing
• Simplifies key management
• Provides consistent access for all members

5. Regular Key Rotation

Rotate API keys periodically (every 90 days recommended):

1. Generate new key with provider
2. Update connection in LangMart
3. Test the connection
4. Revoke the old key with provider

6. Monitor Connection Health

Regularly check your connections dashboard for:

• Error status connections
• Connections approaching rate limits
• Unused connections that can be removed

Related Topics

• Connections Overview - Understanding connections
• Adding Connections - Initial setup guide
• API Key Security - Best practices for key management