Reference
API reference
Base URL: https://fuelline.dev — all API paths live under /v1. Fully OpenAI-compatible.
Creates a completion for a chat conversation. Routed across providers with automatic failover; supports streaming.
{
"model": "zai-org/GLM-5.3-Flash", // required
"messages": [ // required, OpenAI format
{"role": "system", "content": "You are helpful."},
{"role": "user", "content": "Hello!"}
],
"stream": false, // SSE when true
"stream_options": {"include_usage": true}, // usage in final SSE chunk
"temperature": 0.7,
"max_tokens": 1024,
"tools": [...], // passed through
"prompt_cache_key": "conv-123" // sticky routing hint
}Response: standard OpenAI ChatCompletion object with a usage block. Unknown request fields are accepted and forwarded as-is.
The body must be a JSON object with a non-empty string model and a non-empty array of message objects. stream accepts a boolean or null (default false). Invalid envelopes return 400 without contacting a provider; multimodal content and tool messages are passed through.
Answer trimming
Leading and trailing whitespace is removed from assistant answer text by default in ordinary and streaming responses. For example, "\n\n391 \n" becomes "391". Interior spaces and line breaks are preserved, including across stream fragments. Reasoning, refusal, tool arguments, non-text content and reported token usage stay unchanged.
To preserve answer whitespace exactly, add "fuelline_trim_response": false. This is useful for code snippets whose first line needs indentation, leading blank lines or a required final newline. The option must be a boolean and is never forwarded upstream. With trimming enabled (absent or true), an explicit n must be an integer from 1 to 32. Trimming follows Java whitespace rules (space, tab, CR/LF and supported Unicode whitespace); non-breaking spaces and zero-width characters are preserved. This option does not enforce a numeric answer.
Streaming retains only a possible whitespace tail, up to 64 Ki UTF-16 units across all choices. Exceeding this bound gives one terminal SSE error with code response_trim_limit. Unreadable events or unsupported choice metadata give response_trim_unverified. These failures cancel the upstream without retry or [DONE]; clients should accept the answer only after successful stream completion.
Optional tool-only output
For a forced function-tool turn, opt in to suppressing assistant answer text and reasoning:
{
"tool_choice": "required",
"fuelline_tool_only": true
}Include these fields alongside your model, messages and a non-empty array of named function tools. A named tool_choice matching a declared function is also supported. Absent or false leaves mixed text/tool output unchanged. Other option types, or true with auto/none/unsupported tools, return 400 before routing. This gateway-only field is never forwarded upstream.
In sync responses, present message.content becomes null and reasoning_content, reasoning and reasoning_details are removed. SSE removes the same four delta fields before, alongside and after calls. Refusal, calls, exact arguments and observed usage remain. Hidden text does not disarm the first-token deadline. Billing includes suppressed upstream tokens.
Standard required/named function turns require a structured permitted call at normal completion. Missing or disallowed calls produce forced_tool_call_unfulfilled: bounded failover before output, then HTTP 502 for sync or a terminal SSE event: error. After output starts, SSE never retries and a rejected stream has no successful terminal finish or [DONE]. Refusal and length remain refusal and truncation. Existing malformed-argument rejection stays in effect.
This lossy policy hides legitimate narration and reasoning too. It does not execute tools, validate argument schemas or establish that hidden reasoning is truthful. Assemble and validate permitted calls and wait for a successful tool finish before execution. Omit the option (or use false) on auto/none turns and when answering from tool results.
Lists routable models. Same shape as the OpenAI endpoint.
{
"object": "list",
"data": [
{
"id": "zai-org/GLM-5.3-Flash",
"object": "model",
"owned_by": "fuelline",
"context_length": 131072,
"max_tokens": 16384
}
]
}Public catalog with pricing — no authentication. Powers the home-page table.
{
"object": "list",
"data": [
{
"id": "zai-org/GLM-5.3-Flash",
"context_length": 131072,
"max_tokens": 16384,
"input_price": 0.20, // USD per 1M input tokens
"output_price": 0.88 // USD per 1M output tokens
}
]
}Liveness probe. Public.
{ "status": "UP", "timestamp": "...", "service": "fuelline-api" }Service metadata (name, version). Public.
Headers
| Header | Endpoints | Description |
|---|---|---|
Authorization: Bearer <key> | /v1/* | Required. API key issued by Fuelline. |
x-session-id | chat completions | Optional. Provider-affinity key for prompts over 32,000 characters; smaller requests use normal provider selection. |
Content-Type: application/json | POST | Required for request bodies. |
Errors
All errors use the OpenAI error shape:
{
"error": {
"message": "human readable message",
"type": "invalid_request_error" | "server_error",
"code": "model_not_found" | "provider_unavailable" | "timeout" | ...
}
}| Status | When |
|---|---|
400 | Invalid JSON or request envelope; envelope errors use invalid_request_error. |
401 | Missing, empty or invalid Bearer key. |
404 | Model not present in the catalog (model_not_found). |
502 | Every route failed or is down (provider_unavailable or a classified server error). |
Streaming requests that fail before the first token are re-routed transparently; a terminal failure arrives as an SSE error event.