Gateway Proxy

The Gateway Proxy provides direct access to AI provider APIs. Use this for provider-specific features not available through the standardized chat completions endpoint.

Gateway Proxy Endpoint

Route requests directly to AI provider endpoints through the gateway.

Endpoint: https://apis.threatwinds.com/api/ai/v1/gateway/{provider}/{endpoint}

Methods: GET, POST, PUT, DELETE

Parameters

Headers

Header	Type	Required	Description
Authorization	string	Optional*	Bearer token for session authentication
api-key	string	Optional*	API key for key-based authentication
api-secret	string	Optional*	API secret for key-based authentication
Content-Type	string	Varies	Provider-specific content type

Note: You must use either Authorization header OR API key/secret combination.

Note: Additional provider-specific headers are passed through to the provider.

Path Parameters

Parameter	Type	Required	Description	Example
provider	string	Yes	AI provider identifier	claude, groq
endpoint	string	Yes	Provider endpoint path	v1/messages, openai/v1/chat/completions

Query Parameters

All query parameters are passed through to the provider.

Request Body

Provider-specific request payload (varies by provider and endpoint).

Supported Providers

Claude (Anthropic)

Provider ID: claude

Base URL: https://api.anthropic.com

Example Endpoints:

• POST /v1/messages - Messages API
• POST /v1/complete - Completions API

Available Models:

• claude-sonnet-4 (maps to claude-sonnet-4-5-20250929)
• claude-opus-4 (maps to claude-opus-4-1-20250805)

Groq

Provider ID: groq

Base URL: https://api.groq.com

Example Endpoints:

• POST /openai/v1/chat/completions - Chat completions
• GET /openai/v1/models - List models

Available Models:

• gpt-oss-20b (maps to openai/gpt-oss-20b)
• gpt-oss-120b (maps to openai/gpt-oss-120b)
• qwen3-32b (maps to qwen/qwen3-32b)
• llama4-maverick (maps to meta-llama/llama-4-maverick-17b-128e-instruct)
• llama4-scout (maps to meta-llama/llama-4-scout-17b-16e-instruct)

Request

Claude Example

To call Claude’s Messages API directly:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/gateway/claude/v1/messages' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude!"
      }
    ]
  }'

Groq Example

To call Groq’s Chat Completions API:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/gateway/groq/openai/v1/chat/completions' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-oss-20b",
    "messages": [
      {
        "role": "user",
        "content": "What is threat intelligence?"
      }
    ]
  }'

Response

The response is passed through directly from the provider with their native format.

Response Schema

Provider-specific response format (varies by provider and endpoint).

Response Headers

All provider response headers are passed through, plus:

Header	Description
x-error	Error description (on error)
x-error-id	Unique error identifier (on error)

Business Logic

Gateway Processing

1. Request Capture: Generates unique interaction ID and captures request
2. URL Resolution: Parses provider’s redirect URL from configuration
3. Client Setup: Retrieves provider client and configures reverse proxy
4. Custom Response Capture: Wraps response writer to capture full response
5. Proxy: Forwards request to provider

Error Codes

Status Code	Description	Possible Cause
200-299	Success	Request successful (provider-specific)
400	Bad Request	Invalid parameters, malformed payload, invalid provider
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions
500	Internal Server Error	Proxy error, provider error

Provider-specific error codes are passed through unchanged.

List Gateway Routes

Get all available routes for a specific provider.

Endpoint: https://apis.threatwinds.com/api/ai/v1/gateway/{provider}

Method: GET

Parameters

Headers

Header	Type	Required	Description
Authorization	string	Optional*	Bearer token for session authentication
api-key	string	Optional*	API key for key-based authentication
api-secret	string	Optional*	API secret for key-based authentication

Path Parameters

Parameter	Type	Required	Description	Example
provider	string	Yes	AI provider identifier	claude, groq

Request

To list routes for a provider:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/ai/v1/gateway/claude' \
  -H 'Authorization: Bearer <token>'

Response

Success Response (200 OK)

[
  {
    "method": "POST",
    "relative_path": "/v1/messages",
    "redirect_to": "https://api.anthropic.com/v1/messages",
    "provider": "claude"
  },
  {
    "method": "POST",
    "relative_path": "/v1/complete",
    "redirect_to": "https://api.anthropic.com/v1/complete",
    "provider": "claude"
  }
]

Response Schema

Field	Type	Description
method	string	HTTP method (GET, POST, PUT, DELETE)
relative_path	string	Endpoint path relative to gateway
redirect_to	string	Full URL to provider endpoint
provider	string	Provider identifier

Use Cases

Provider-Specific Features

Access features not available in standardized endpoint:

# Claude: Use streaming
curl -X POST \
  'https://apis.threatwinds.com/api/ai/v1/gateway/claude/v1/messages' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Tell me a story"}]
  }'

Fast Inference with Groq

Use Groq for ultra-fast inference:

curl -X POST \
  'https://apis.threatwinds.com/api/ai/v1/gateway/groq/openai/v1/chat/completions' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "messages": [{"role": "user", "content": "Explain threat intelligence"}]
  }'

Best Practices

When to Use Gateway vs Chat Completions

Use Chat Completions for:

• Standard text generation
• Cross-provider compatibility
• Simplified API interface

Use Gateway for:

• Provider-specific features (streaming, extended thinking, etc.)
• Direct provider API access with native request format
• Beta/experimental features
• Fine-grained control over provider-specific parameters

Request Construction

1. Check Provider Docs: Refer to provider documentation for request format
2. Include Required Headers: Some providers require specific headers
3. Validate Payload: Ensure request matches provider schema
4. Handle Provider Errors: Be prepared for provider-specific error formats

Error Handling

import requests

def gateway_request(provider, endpoint, token, payload, max_retries=3):
    url = f'https://apis.threatwinds.com/api/ai/v1/gateway/{provider}/{endpoint}'

    for attempt in range(max_retries):
        try:
            response = requests.post(
                url,
                headers={'Authorization': f'Bearer {token}'},
                json=payload,
                timeout=60
            )

            # Log interaction ID from response
            interaction_id = response.headers.get('x-interaction-id')
            print(f"Interaction ID: {interaction_id}")

            response.raise_for_status()
            return response.json()

        except requests.exceptions.HTTPError as e:
            # Provider-specific error
            error_detail = response.json() if response.content else None
            print(f"Provider error: {error_detail}")

            if response.status_code >= 500 and attempt < max_retries - 1:
                # Retry on server errors
                time.sleep(2 ** attempt)
                continue

            raise

        except requests.exceptions.RequestException as e:
            # Network/timeout error
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

    return None

Security Considerations

1. Authentication: Gateway handles ThreatWinds auth, provider auth handled internally
2. API Keys: Provider API keys managed server-side
3. Rate Limiting: Subject to both ThreatWinds and provider rate limits
4. Data Privacy: All requests logged to OpenSearch for audit

Performance

1. Minimal Overhead: Gateway adds ~10-50ms latency
2. Direct Proxy: Requests proxied directly to providers
3. Streaming Support: Supports provider streaming where available
4. Parallel Requests: Make multiple gateway requests in parallel

Gateway Architecture

Client Request
  ↓
ThreatWinds AI API Gateway
  ↓
[Authentication]
  ↓
Provider Selection (claude/groq)
  ↓
Reverse Proxy to Provider
  ↓
Provider API (Anthropic/Groq)
  ↓
Response to Client

Comparison: Chat Completions vs Gateway

Feature	Chat Completions	Gateway
Interface	Standardized	Provider-specific
Providers	All	All + external services
Features	Text generation	All provider features
Response Format	Unified	Provider-native
Use Case	General chat	Specialized features
Simplicity	High	Medium
Flexibility	Medium	High

Troubleshooting

Common Issues

Issue	Cause	Solution
400 Bad Request	Invalid provider payload	Check provider API documentation
404 Not Found	Provider not configured	Verify provider ID is correct
500 Server Error	Provider API error	Check provider status page
Timeout	Long-running request	Increase timeout or use streaming

Debugging

1. Check Logs: Search OpenSearch for interaction ID
2. Verify Payload: Ensure request matches provider schema
3. Test Direct: Try request directly to provider to isolate issue
4. Check Provider Status: Verify provider API is operational

Getting Help

When reporting issues, include:

• Interaction ID from response headers
• Provider and endpoint
• Request payload (sanitized)
• Error message and status code