Chat Completions

Overview

POST /v1/chat/completions accepts OpenAI-format request bodies and routes them through Aurora's pipeline: alias resolution ? workflow matching ? guardrails ? cache check ? failover ? provider call ? usage logging ? response.

This means aliases, model access rules, workflows, guardrails, response caching, failover, and usage tracking all apply automatically.

Request

curl http://your-aurora-host/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'
 

Standard Parameters

Aurora accepts parameters generously and translates them per provider requirements (e.g., max_tokens ? max_completion_tokens for OpenAI reasoning models).

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1728000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 10,
    "total_tokens": 35
  }
}
 

Streaming

Add "stream": true to the request body. Aurora streams the response using server-sent events (SSE) compatible with OpenAI's streaming format.

curl http://your-aurora-host/v1/chat/completions \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Count to 5"}],
    "stream": true
  }'
 

Response headers

Aurora adds response headers that tell you how the request was processed. None of these are required by OpenAI clients; ignore them if you do not care.

Aurora does not emit headers for combo selection, failover selection, or workflow selection. To see which upstream model actually answered a combo or failover request, read the response body's model field (it is the resolved upstream ID, not the alias or combo name) or query the usage log for the request ID.

To force a cache miss on a single request, send Cache-Control: no-cache or Cache-Control: no-store. To pin a specific cache layer, send X-Cache-Type: exact or X-Cache-Type: semantic.

SDK Usage

Python

from openai import OpenAI
 
client = OpenAI(
    base_url="http://your-aurora-host/v1",
    api_key="sk-aurora-...",
)
 
completion = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
 

JavaScript

import OpenAI from "openai";
 
const client = new OpenAI({
  baseURL: "http://your-aurora-host/v1",
  apiKey: "sk-aurora-...",
});
 
const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});
 

Pipeline Integration

The chat completions endpoint runs through:

• Alias resolution � model field resolves aliases before upstream call
• Workflow matching � Scoped policy selection by provider, model, user_path
• Guardrails � System prompt injection, PII redaction, content filtering
• Response cache � Exact-match and semantic cache (non-streaming only)
• Failover � Cross-model fallback on provider errors
• Usage tracking � Token and cost accounting per request