API Reference

Request Headers

VectorAxis adds no proprietary fields to your request body — every capability is a plain HTTP header. That means you keep the stock OpenAI SDK and JSON body exactly as they are, and turn features on per request by adding a header. Pass them through the SDK’s extra_headers argument or set them directly on your HTTP client.

Credentials — one group required, mutually exclusive

Header	What it does
Authorization: Bearer vk-<slug>	Preferred. Pass the virtual key slug as a standard bearer token — set the OpenAI SDK’s api_key to the slug and it’s sent here automatically. Resolved in-process to provider + decrypted key.
x-virtual-key	The virtual key slug as a dedicated header — an alternative to the bearer form. Takes precedence when both are present.
x-provider	Provider id (e.g. OPENAI, ANTHROPIC, GROQ), normalised to SCREAMING_SNAKE_CASE. Use with x-api-key for the direct-credential path. See Providers.
x-api-key	Your raw provider API key. Use with x-provider. Never logged.

A virtual key auto-attaches org/workspace attribution, budget enforcement, and usage accounting; direct credentials don’t. See the note on Providers.

Caching

Header	What it does
x-cache-mode	simple (exact-match) or semantic. Caching is opt-in — omit this and the request is DISABLED. Ignored when stream: true. See Caching.
x-cache-ttl	Per-request cache lifetime, in seconds.
x-cache-force-refresh	true bypasses the cached entry and refreshes it with a fresh call. Only refreshes an already-enabled cache — it never turns caching on.

Retry & fallback

Header	What it does
x-retry-count	Max retries on a failing call, 0–5 (default 0). Exponential backoff. See Retry & Fallback.
x-retry-status-codes	Comma-separated HTTP codes that should trigger a retry, e.g. 429,503.
x-fallback-{n}-provider	Provider for fallback attempt n (1–5), tried in order if the primary fails.
x-fallback-{n}-api-key	API key for fallback provider n.
x-fallback-{n}-model	Optional model override for fallback n.

Retry and fallback are disabled on streaming requests — a stream can’t be replayed mid-flight.

Routing, scoping & features

Header	What it does
x-config	Slug of a routing config to apply (weighted split, fallback chain, conditions).
x-guardrail	Slug of a guardrail to enforce on the input/output phases; comma-separate to run several in order. Adds to whatever the virtual key already binds — it never replaces it, so this header cannot weaken a key’s policy. Omit it entirely and the key’s own guardrails still run.
x-organization	Organisation id for log attribution and plan-limit scoping. Ignored when a virtual key supplies its own org (the key’s org is authoritative).
x-workspace-id	Workspace UUID. Scopes resource queries and is written to the log record.
x-metadata	Your own key/value tags, echoed into logs and analytics for grouping and cost attribution.
x-prompt-slug	Use a managed prompt by slug (alternative to the /v1/prompts/{slug}/completions path).
x-prompt-version	Pin a specific prompt version or label; defaults to the published one.

Google Vertex AI overrides

Header	What it does
x-vertex-project	Override the GCP project resolved from the Vertex virtual key credential, per request.
x-vertex-region	Override the region; use global for the multi-region endpoint.
x-vertex-model	Mainly internal — carries the model id for Claude-on-Vertex, whose URL embeds the model in the path.

Response headers

On a non-streaming response, VectorAxis echoes back what actually happened (streaming responses omit these — they are committed before the per-request result is known):

Header	What it does
x-cache-status	HIT / SEMANTIC_HIT / MISS / REFRESH / BYPASS / DISABLED.
x-retry-count	Retries actually performed.
x-fallback-provider	The fallback provider that served the request, if any.
x-virtual-key-slug	The virtual key that was resolved.
x-guardrail-status	The guardrail outcome, merged across every guardrail that applied (most severe wins) — PASS / BLOCK / REDACT / MONITOR / BYPASS.

Sending headers with the OpenAI SDK

python

from openai import OpenAI

client = OpenAI(base_url="https://api.vectoraxis.ai/v1", api_key="vk-1a2b3c4d5e6f7a8b")

client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "x-cache-mode": "semantic",
        "x-retry-count": "2",
        "x-fallback-1-provider": "ANTHROPIC",
        "x-fallback-1-api-key": "sk-ant-...",
        "x-guardrail": "pii-redact",
        "x-workspace-id": "6f1c...",
    },
)

Looking for the paths these headers attach to? See Endpoints.