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, openai, gemini, groq, vllm
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

Example Endpoints:

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

Available Models:

  • claude-sonnet-4
  • claude-opus-4
  • claude-haiku-4

OpenAI

Provider ID: openai

Example Endpoints:

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

Available Models:

  • gpt-5
  • gpt-5-mini

Gemini (Google)

Provider ID: gemini

Example Endpoints:

  • POST /v1beta/models/{model}:generateContent - Generate content
  • GET /v1beta/models - List models

Available Models:

  • gemini-3-pro
  • gemini-3-flash-lite
  • gemini-3-flash

Groq

Provider ID: groq

Example Endpoints:

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

Available Models:

  • gpt-oss-20b
  • gpt-oss-120b
  • qwen3-32b
  • llama4-maverick
  • llama4-scout

vLLM (ThreatWinds)

Provider ID: vllm

Example Endpoints:

  • POST /v1/chat/completions - Chat completions
  • POST /tokenize - Token counting

Available Models:

  • silas-1.0 (Silas - Cybersecurity AI Assistant)
  • silas-1.0-pro (Silas Pro - Full-precision cybersecurity model)

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-6",
    "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-interaction-id Unique identifier for the request interaction
x-error Error description (on error)
x-error-id Unique error identifier (on error)

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-6",
    "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 is handled internally
  2. API Keys: Provider API keys are managed server-side, you only need ThreatWinds credentials
  3. Rate Limiting: Subject to both ThreatWinds and provider rate limits

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

Getting Help

When reporting issues, include:

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