Skip to main content

​
Required Headers

These headers must be included with every request to Oximy Gateway:
HeaderDescriptionExample
x-oximy-api-keyYour Oximy Gateway API keyoxi-live-xxxxxxxxxxxxxxxxxxxxxxxxx
x-oximy-project-idYour project identifiermy-project-slug
AuthorizationYour AI provider API keyBearer sk-your-openai-key

​
Example Configuration

const openai = new OpenAI({
  baseURL: 'https://gateway.oximy.com/v1',
  apiKey: 'your-openai-api-key',
  defaultHeaders: {
    'x-oximy-api-key': 'oxi-live-YOUR_API_KEY',
    'x-oximy-project-id': 'your-project-slug'
  }
});

​
Optional Headers

These headers provide additional control over Gateway behavior:
HeaderDescriptionValuesDefault
x-oximy-providerSpecify AI provideropenai, anthropic, google, etc.openai
x-oximy-disableDisable guardrailstrue, falsefalse
x-oximy-cacheBypass guardrails cachetrue, falsefalse

​
Provider Selection

Use x-oximy-provider to explicitly specify which AI provider to use: 
// Use Anthropic instead of OpenAI
const response = await openai.chat.completions.create({
  model: 'claude-3-5-sonnet-20241022',
  messages: [{ role: 'user', content: 'Hello!' }]
}, {
  headers: {
    'x-oximy-provider': 'anthropic'
  }
});

​
Disabling Guardrails

For testing or when guardrails aren’t needed: 
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Sensitive data here' }]
}, {
  headers: {
    'x-oximy-disable': 'true'
  }
});

​
Response Headers

Oximy Gateway adds these headers to every response:
HeaderDescriptionExample
x-oximy-guardrails-statusProcessing statussuccess, failed, bypassed
x-oximy-violationsTotal violations detected2
x-oximy-request-violationsRequest violations count1
x-oximy-response-violationsResponse violations count1
x-oximy-cache-hitConfiguration cache statustrue, false
x-oximy-cache-timestampCache timestamp2025-01-27T10:30:00.000Z

​
Checking Response Headers

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'My email is [email protected]' }]
});

// Check guardrails status
console.log('Status:', response.headers['x-oximy-guardrails-status']);
console.log('Violations:', response.headers['x-oximy-violations']);
console.log('Cache hit:', response.headers['x-oximy-cache-hit']);

​
Supported AI Providers

Gateway supports 20+ AI providers. Here are the most common ones:
ProviderHeader ValueExample Model
OpenAIopenaigpt-4o
Anthropicanthropicclaude-3-5-sonnet-20241022
Googlegooglegemini-1.5-pro
Azure OpenAIazure-openaigpt-4o
Together AItogethermeta-llama/Llama-2-70b-chat-hf
Coherecoherecommand
Perplexityperplexityllama-3-sonar-small-128k-online
Groqgroqllama3-70b-8192

​
Error Handling

When headers are missing or invalid, Gateway returns clear error messages:
ErrorDescriptionSolution
missing_api_keyNo x-oximy-api-key headerAdd required header
missing_project_idNo x-oximy-project-id headerAdd project identifier
invalid_api_keyInvalid API key formatCheck key format
gateway_unreachableCannot connect to AI providerCheck network connectivity

​
Example Error Response

{
  "error": {
    "message": "Missing required header: x-oximy-api-key",
    "type": "missing_api_key",
    "code": "missing_api_key"
  }
}

​
Best Practices

​
1. Environment Variables

Store your credentials securely: 
OXIMY_API_KEY=oxi-live-YOUR_API_KEY
OXIMY_PROJECT_ID=your-project-slug
OPENAI_API_KEY=sk-your-openai-key

​
2. Provider Fallback

Implement fallback logic for reliability: 
async function robustRequest(prompt, providers = ['openai', 'anthropic']) {
  for (const provider of providers) {
    try {
      const response = await openai.chat.completions.create({
        model: 'gpt-4o',
        messages: [{ role: 'user', content: prompt }]
      }, {
        headers: { 'x-oximy-provider': provider }
      });
      return response;
    } catch (error) {
      console.log(`Provider ${provider} failed, trying next...`);
      continue;
    }
  }
  throw new Error('All providers failed');
}

​
FAQ

​
How do I get an API key?

  1. Visit the Oximy Dashboard
  2. Sign up or log in to your account
  3. Navigate to “API Keys” section
  4. Click “Create New Key”
  5. Copy your x-oximy-api-key and x-oximy-project-id

​
What are the rate limits?

Oximy Gateway inherits rate limits from your AI provider:
  • OpenAI: Based on your OpenAI plan (free tier: 3 requests/minute, paid: varies by model)
  • Anthropic: Based on your Anthropic plan (free tier: 5 requests/minute, paid: varies by model)
  • Google: Based on your Google AI Studio quota
Gateway adds minimal overhead and doesn’t impose additional rate limits.

​
Can I use multiple providers simultaneously?

Yes. You can switch providers per request using the x-oximy-provider header, or implement fallback logic to try multiple providers in sequence.

​
How do I disable guardrails for testing?

Set the x-oximy-disable header to true: 
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Test data' }]
}, {
  headers: { 'x-oximy-disable': 'true' }
});

​
What happens if guardrails fail?

Gateway uses a “fail-open” approach. If guardrails processing fails, the request continues without protection. Check the x-oximy-guardrails-status header to monitor guardrails health.