POST /v1/chat/completions

Inference APIs

Create a chat completion using OpenAI-compatible request and response shapes, with gateway rewrites, caching, and streaming support.

POST/v1/chat/completions

Request

Auth: tenant auth when enabled; otherwise dev mode is open
Content-Type: application/json
Max body size: 4 MiB
Streaming: SSE when stream=true

Request fields

Field	Type	Required	Notes
`model`	string	yes	Alias or direct `provider/upstream-model` string
`messages`	array	yes	OpenAI chat messages
`stream`	boolean	no	Enables SSE streaming
`max_tokens`	integer	no	Passed upstream when present
`max_completion_tokens`	integer	no	Passed upstream when present
`temperature`	number	no	Passed upstream when present
`top_p`	number	no	Passed upstream when present
`tools`	any JSON	no	Passed through unchanged
`tool_choice`	any JSON	no	Passed through unchanged
`response_format`	any JSON	no	Passed through unchanged
`stream_options.include_usage`	boolean	no	Enables usage chunks on stream-capable upstreams
`metadata` or `aramm`	object	no	Attribution fields stripped before upstream dispatch
any other fields	any JSON	no	Preserved in `Extra` and forwarded unchanged

Response schema

Field	Type	Required	Notes
`id`	string	yes	Gateway-owned completion ID
`object`	string	yes	Always `chat.completion` for unary responses
`created`	int64	yes	Unix timestamp from the gateway boundary
`model`	string	yes	Rewritten to the public alias
`choices`	array	yes	Always present
`choices[].index`	integer	yes	Choice index
`choices[].message.role`	string	yes	Usually `assistant`
`choices[].message.content`	string	no	Assistant content when returned as text
`choices[].finish_reason`	string	yes	Stop reason from the upstream provider
`usage`	object	no	Present when the upstream provides usage
`usage.prompt_tokens`	integer	no	Prompt token count
`usage.completion_tokens`	integer	no	Completion token count
`usage.total_tokens`	integer	no	Total token count
`usage.cost`	number	no	Gateway estimate when available

Errors

HTTP	Code	When
`400`	`invalid_request`	Malformed JSON, missing `model`, missing `messages`, or invalid message content
`400`	`invalid_model`	Unknown model or unsupported route resolution
`400`	`provider_not_configured`	Provider missing from config or unavailable
`422`	`pii_detected`	PII blocked in pre-call or post-call guardrails
`422`	`BLOCKED_POLICY_VIOLATION`	PDPA keyword policy block
`403`	`CROSS_BORDER_TRANSFER_BLOCKED`	PDPA cross-border transfer rejected
`429`	`rate_limit_exceeded`	Tenant rate limit exceeded
`402`	`monthly_budget_exceeded`	Monthly spend limit exceeded
`402`	`insufficient_credits`	Credit balance too low
`502`	`upstream_error`	Provider failure without a normalized provider error body

Notes

Unary requests may be served from the exact response cache.
Streaming requests proxy OpenAI-style SSE frames frame-by-frame.
Response model is rewritten to the public alias.
Response id is rewritten to a gateway-owned completion ID.
metadata and aramm body fields are stripped before upstream dispatch.

curl https://router.aramm.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ARAMM_API_KEY" \
-d '{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is an LLM gateway?"
    }
  ],
  "max_tokens": 1024,
  "temperature": 0.7
}'

Response 200

{
"id": "chatcmpl-abc123def456",
"object": "chat.completion",
"created": 1748200000,
"model": "openai/gpt-4o-mini",
"choices": [
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "An LLM gateway is a unified API layer that routes requests to multiple large language model providers. It normalizes different API formats, handles failover, load balancing, and provides centralized monitoring and cost tracking across providers like OpenAI, Anthropic, Google, and others."
    },
    "finish_reason": "stop"
  }
],
"usage": {
  "prompt_tokens": 24,
  "completion_tokens": 52,
  "total_tokens": 76,
  "cost": 0.000038
}
}