Home/Docs/API Reference
TECHNICAL SPECIFICATIONS

API & Header Reference

Reference page detailing all supported headers, endpoint configurations, and standard JSON response payloads.

🔑 Authentication

All requests dispatched through the Selixes gateway must include your secure API key in standard HTTP Authorization headers:

Authorization: Bearer selixes_live_prodkey982

💡 Legacy Support: The gateway is fully backwards-compatible. You can continue to authenticate using your existing keys (prefixed with apishield_live_) during the migration phase.

⚙️ Custom Budget Headers

Pass these optional parameters within your standard transit headers to activate active budget guards on the gateway layer:

HTTP HeaderTypeDescription
x-selixes-session-idStringUnique identifier mapping reasoning budgets across an active agent run. (Legacy fallback: x-apishield-session-id)
x-selixes-max-session-costFloatSession spending cap (e.g. 0.15 for $0.15 limit). Blocks further calls if exceeded. (Legacy fallback: x-apishield-max-session-cost)
x-selixes-max-concurrent-callsIntegerConcurrency connection caps (e.g. 3 active calls). Limits parallel agent swarm bursts. (Legacy fallback: x-apishield-max-concurrent-calls)
x-selixes-timeoutIntegerUpstream provider timeout threshold in milliseconds. Reroutes to Standby if exceeded. (Legacy fallback: x-apishield-timeout)
x-selixes-routing-policyStringOptimization strategy for selecting models (values: "balanced" | "lowest-latency" | "cost-arbitrage").
x-selixes-latency-tolerance-msIntegerMaximum tolerated latency before falling back to the primary provider.
x-selixes-fallback-routeStringOverride standby targets manually (values: "anthropic" | "gemini" | "ollama"). (Legacy fallback: x-apishield-fallback-route)

💡 Compatibility: You can continue to dispatch requests with your legacy x-apishield-* headers. The gateway translates them seamlessly to x-selixes-* primitives.

📥 JSON Response Payloads

1. Successful Completion Payload (with Custom Headers)

// HTTP Headers returned by gateway:
// x-cache: MISS (or HIT)
// x-provider-chain: openai:200
// x-selixes-runtime-mode: redis

{
  "id": "chatcmpl-982739",
  "object": "chat.completion",
  "created": 1780087476,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Analysis completed successfully." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 128, "completion_tokens": 64, "total_tokens": 192 }
}

2. Intercepted Budget Gate Payload (Standard HTTP 429 Error)

// HTTP Status returned: 429 Too Many Requests
{
  "statusCode": 429,
  "error": "runaway_agent_protection",
  "message": "Runaway Agent Intercepted: Session budget exceeded (MAX_COST_EXCEEDED).",
  "sessionId": "session_crm_batch_02",
  "terminationReason": "MAX_COST_EXCEEDED",
  "requestId": "fe2c2d5f-d148-4a1d-9079-efa5181b4cd2"
}