openapi: 3.0.3 info: title: GenieX Server version: 0.0.0 description: | GenieX Server - OpenAI compatible API endpoints paths: /v1/chat/completions: post: summary: Creates a model response for the given chat conversation description: This endpoint generates a model response for a given conversation, which can include text and images. It supports both single-turn and multi-turn conversations and can be used for various tasks like question answering, code generation, and function calling. operationId: PostV1ChatCompletions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChatCompletionRequest" responses: "200": description: Successful response for non-streaming requests content: application/json: schema: $ref: "#/components/schemas/ChatCompletionResponse" /v1/completions: post: summary: Creates a raw text completion for the given prompt description: | Generates a continuation of the prompt with no chat template applied — the prompt is passed to the model verbatim. Intended for clients that build the full prompt themselves, e.g. editor fill-in-the-middle (FIM) code autocompletion; include the model's FIM tokens in `prompt` directly. LLM models only. operationId: PostV1Completions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CompletionRequest" responses: "200": description: Successful response for non-streaming requests content: application/json: schema: $ref: "#/components/schemas/CompletionResponse" /v1/logits: post: summary: Raw logits from a single prefill-only forward pass description: | Runs one non-autoregressive forward pass over pre-tokenized input and returns the raw LM-head logits. This is NOT the OpenAI generative logprobs semantics — no sampling or decode loop runs. Intended for on-target accuracy metrics (perplexity, MMLU, MMMU). Input is pre-tokenized (`input_ids`); the server does not tokenize text here. operationId: PostV1Logits requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ForwardLogitsRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ForwardLogitsResponse" /v1/decisions: post: summary: Evaluate questions with the OpenAI Decisions API description: | Scores questions against shared text input using a cached local llama_cpp LLM and native logits. This server accepts text only; image input is unsupported. Candidate probabilities are normalized over the supplied choices or levels and are not calibrated. operationId: PostV1Decisions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DecisionRequest" responses: "200": description: Answers in question order with token usage content: application/json: schema: $ref: "#/components/schemas/DecisionResponse" "400": description: Unsupported model or model scoring error "413": description: Request exceeds 1 MiB "422": description: Invalid request or unsupported input modality /status: get: summary: Reports server liveness and the state of loaded models description: Served outside the request lock, so it responds while a generation is running. State is one of loading, active, idle. operationId: GetStatus servers: - url: / responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/StatusResponse" /health: get: summary: Liveness and readiness probe description: Served outside the request lock. Returns 503 while a model is loading. operationId: GetHealth servers: - url: / responses: "200": description: Ready content: application/json: schema: type: object properties: status: type: string example: ok "503": description: A model is loading /metrics: get: summary: Prometheus metrics description: Prometheus text format, counters prefixed with geniex. Only available when the server is started with --metrics; otherwise returns 501. operationId: GetMetrics servers: - url: / responses: "200": description: Prometheus text exposition content: text/plain: schema: type: string "501": description: Metrics are disabled /v1/models: get: summary: Lists the currently available models description: Lists the currently available models, and provides basic information about each one such as the owner and availability operationId: GetV1Models responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ModelsListResponse" /v1/models/{model}: get: summary: Retrieves a model instance description: Retrieves a model instance, providing basic information about the model such as the owner and permissioning operationId: GetV1ModelsModel parameters: - name: model in: path required: true description: The ID of the model to use for this request schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ModelResponse" "404": description: Model not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" components: schemas: StatusResponse: type: object required: [alive, models] properties: alive: type: boolean version: type: string uptime_seconds: type: integer format: int64 keepalive_seconds: type: integer format: int64 models: type: array items: type: object properties: id: type: string type: type: string enum: [llm, vlm] runtime: type: string device: type: string state: type: string enum: [loading, active, idle] loaded_at: type: string format: date-time last_activity: type: string format: date-time idle_seconds: type: integer format: int64 # ---------- Decisions ---------- DecisionRequest: type: object required: [input, questions] example: model: "local/decision-model:Q4_K_M" input: "Our checkout has returned 500 errors since 9am." questions: - name: "label" type: choice instructions: "Which label fits this ticket?" choices: - value: "billing" description: "Payments and refunds" - value: "bug" description: "Software errors" - value: "account" description: "Login and account access" - name: "urgent" type: predicate instructions: "Is a critical business operation currently blocked?" - name: "severity" type: score instructions: "How severe is the issue?" levels: - label: "low" - label: "moderate" - label: "critical" properties: model: type: string description: Cached llama_cpp LLM or VLM; omit only when a server model is set via `geniex serve --model` / `GENIEX_MODEL`. input: description: Nonempty text or user messages containing text only. Images are unsupported. oneOf: - type: string minLength: 1 - type: array minItems: 1 items: $ref: "#/components/schemas/DecisionInputMessage" questions: type: array minItems: 1 maxItems: 64 description: Ordered questions with unique optional names. items: oneOf: - $ref: "#/components/schemas/DecisionPredicateQuestion" - $ref: "#/components/schemas/DecisionChoiceQuestion" - $ref: "#/components/schemas/DecisionScoreQuestion" nctx: type: integer description: Context size; defaults to the server setting. ngl: type: integer description: Number of GPU layers; defaults to the server setting. compute: type: string description: Compute-unit alias; defaults to the server setting. power_mode: type: string description: Power mode; defaults to the server setting. DecisionInputMessage: type: object required: [content] properties: type: type: string enum: [message] default: message role: type: string enum: [user] default: user content: description: Text or an ordered array of input_text parts. Images are unsupported. oneOf: - type: string - type: array minItems: 1 items: $ref: "#/components/schemas/DecisionInputTextPart" DecisionInputTextPart: type: object required: [type, text] properties: type: type: string enum: [input_text] text: type: string DecisionPredicateQuestion: type: object required: [type, instructions] properties: type: type: string enum: [predicate] name: type: string description: Optional unique question name; response name is null if omitted. instructions: type: string minLength: 1 DecisionChoiceQuestion: type: object required: [type, instructions, choices] properties: type: type: string enum: [choice] name: type: string description: Optional unique question name; response name is null if omitted. instructions: type: string minLength: 1 choices: type: array minItems: 2 maxItems: 26 items: $ref: "#/components/schemas/DecisionChoice" DecisionChoice: type: object required: [value] properties: value: oneOf: - type: string - type: boolean description: type: string DecisionScoreQuestion: type: object required: [type, instructions, levels] properties: type: type: string enum: [score] name: type: string description: Optional unique question name; response name is null if omitted. instructions: type: string minLength: 1 levels: type: array minItems: 2 maxItems: 10 items: $ref: "#/components/schemas/DecisionScoreLevel" DecisionScoreLevel: type: object required: [label] properties: label: type: string minLength: 1 description: type: string DecisionResponse: type: object required: [answers, model, usage] properties: answers: type: array description: One answer for each question, in question order. items: oneOf: - $ref: "#/components/schemas/DecisionPredicateAnswer" - $ref: "#/components/schemas/DecisionChoiceAnswer" - $ref: "#/components/schemas/DecisionScoreAnswer" model: type: string usage: $ref: "#/components/schemas/DecisionUsage" DecisionPredicateAnswer: type: object required: [type, name, probability] properties: type: type: string enum: [predicate] name: type: string nullable: true probability: type: number minimum: 0 maximum: 1 DecisionChoiceAnswer: type: object required: [type, name, choice, probabilities, confidence] properties: type: type: string enum: [choice] name: type: string nullable: true choice: oneOf: - type: string - type: boolean probabilities: type: array items: $ref: "#/components/schemas/DecisionChoiceProbability" confidence: type: number minimum: 0 maximum: 1 DecisionChoiceProbability: type: object required: [value, probability] properties: value: oneOf: - type: string - type: boolean probability: type: number minimum: 0 maximum: 1 DecisionScoreAnswer: type: object required: [type, name, score, probabilities, confidence] properties: type: type: string enum: [score] name: type: string nullable: true score: type: number probabilities: type: array items: $ref: "#/components/schemas/DecisionScoreProbability" confidence: type: number minimum: 0 maximum: 1 DecisionScoreProbability: type: object required: [value, label, probability] properties: value: type: integer minimum: 0 label: type: string probability: type: number minimum: 0 maximum: 1 DecisionUsage: type: object required: [input_tokens, input_tokens_details, output_tokens, output_tokens_details, total_tokens] properties: input_tokens: type: integer input_tokens_details: type: object required: [cache_write_tokens, cached_tokens] properties: cache_write_tokens: type: integer cached_tokens: type: integer output_tokens: type: integer output_tokens_details: type: object required: [reasoning_tokens] properties: reasoning_tokens: type: integer total_tokens: type: integer # ---------- Logits ---------- ForwardLogitsRequest: type: object required: [input_ids] example: model: "qualcomm/Qwen3-4B-Instruct-2507" input_ids: [1, 2, 3, 4] last_only: false top_n: 20 properties: model: type: string description: LLM model; omit only when a server model is set via `geniex serve --model` / `GENIEX_MODEL`. input_ids: type: array items: type: integer description: Pre-tokenized token ids; the caller owns any special tokens. last_only: type: boolean description: "false (default): every position. true: last token's row only." top_n: type: integer description: "Keep only the top-N logits per row (default 20). 0 returns the full vocabulary per row." nctx: type: integer ngl: type: integer compute: type: string power_mode: type: string ForwardLogitsResponse: type: object properties: model: type: string n_rows: type: integer vocab_size: type: integer top_n: type: integer description: Effective top-N used (0 means full vocabulary per row). rows: type: array description: One entry per emitted position. items: type: object properties: token_ids: type: array items: type: integer description: Token id per logit; omitted when top_n is 0 (column index is the token id). logits: type: array items: type: number description: top_n > 0 — top logits sorted descending; top_n == 0 — full vocab in token-id order. # ---------- Completions ---------- CompletionRequest: type: object required: [prompt] example: model: "qualcomm/Qwen3-4B-Instruct-2507" prompt: "def fibonacci(n):" max_tokens: 64 temperature: 0.2 stream: false properties: model: type: string description: LLM model; omit only when a server model is set via `geniex serve --model` / `GENIEX_MODEL`. prompt: type: string description: The prompt to complete, passed to the model verbatim (no chat template). A single-element string array is also accepted. max_tokens: type: integer minimum: 1 default: 16 description: The maximum number of tokens to generate suffix: type: string description: Not supported — include the model's FIM tokens in `prompt` instead echo: type: boolean default: false description: Echo back the prompt in addition to the completion stop: oneOf: - type: string - type: array items: type: string description: Sequences where generation stops; the returned text does not contain them temperature: type: number format: float minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Omit for the plugin default; 0 decodes greedily top_p: type: number format: float minimum: 0 maximum: 1 description: An alternative to sampling with temperature, called nucleus sampling seed: type: integer description: Best-effort deterministic sampling seed presence_penalty: type: number format: float minimum: -2 maximum: 2 description: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far frequency_penalty: type: number format: float minimum: -2 maximum: 2 description: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far stream: type: boolean description: If set, partial text deltas will be sent default: false stream_options: type: object description: Options for streaming responses. Only used when stream is true. properties: include_usage: type: boolean description: If set, an additional chunk will be streamed with token usage statistics for the entire request top_k: type: integer minimum: 0 description: An alternative to sampling with temperature, called top-k sampling min_p: type: number format: float minimum: 0 maximum: 1 description: Minimum token probability, scaled by the probability of the most likely token repetition_penalty: type: number format: float minimum: 0 maximum: 100 description: The parameter for repetition penalty. 1.0 means no penalty nctx: type: integer minimum: 1 description: Context window size (llama_cpp only). Omit to use the server default set via `geniex serve --nctx` / `GENIEX_NCTX` (4096 out of the box). ngl: type: integer description: Number of GPU/NPU layers to offload (llama_cpp only). Omit to use the server default set via `geniex serve --ngl` / `GENIEX_NGL` (999 out of the box); the server chooses the correct layout per backend. compute: type: string enum: [cpu, gpu, npu, hybrid] description: Compute unit to run on. Omit to use the server default set via `geniex serve --compute` / `GENIEX_COMPUTE`. QAIRT is NPU-only; other aliases are coerced with a warning. power_mode: type: string enum: [low_power_saver, power_saver, high_power_saver, low_balanced, balanced, high_performance, sustained_high_performance, burst, default] description: HTP power/clock-management mode, shared by qairt and llama_cpp. Omit to use the server default set via `geniex serve --power-mode` / `GENIEX_POWER_MODE` (burst out of the box). CompletionResponse: type: object properties: object: type: string example: "text_completion" choices: type: array items: type: object properties: index: type: integer text: type: string description: The generated continuation of the prompt finish_reason: type: string enum: [stop, length] usage: $ref: "#/components/schemas/TokenUsage" # ---------- Chat ---------- ChatCompletionRequest: type: object required: [messages] example: model: "qualcomm/Qwen3-4B-Instruct-2507" messages: - role: "user" content: "Hello! Briefly introduce yourself." nctx: 0 max_completion_tokens: 2048 temperature: 0.8 top_p: 0.95 stream: false enable_think: true properties: model: type: string description: Model to use; omit only when a server model is set via `geniex serve --model` / `GENIEX_MODEL`. messages: type: array items: $ref: "#/components/schemas/ChatMessage" description: A list of messages comprising the conversation so far nctx: type: integer minimum: 1 description: Context window size (llama_cpp only). Omit to use the server default set via `geniex serve --nctx` / `GENIEX_NCTX` (4096 out of the box). max_completion_tokens: type: integer minimum: 1 description: An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. default: 2048 max_tokens: type: integer minimum: 1 description: "Deprecated alias for `max_completion_tokens`, accepted for compatibility with older OpenAI clients. Ignored when `max_completion_tokens` is also present." deprecated: true temperature: type: number format: float minimum: 0 maximum: 2 default: 0.8 description: What sampling temperature to use, between 0 and 2. Omit for the plugin default; 0 decodes greedily top_p: type: number format: float minimum: 0 maximum: 1 default: 0.95 description: An alternative to sampling with temperature, called nucleus sampling stream: type: boolean description: If set, partial message deltas will be sent default: false stream_options: type: object description: Options for streaming responses. Only used when stream is true. properties: include_usage: type: boolean description: If set, an additional chunk will be streamed with token usage statistics for the entire request presence_penalty: type: number format: float minimum: -2 maximum: 2 description: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far frequency_penalty: type: number format: float minimum: -2 maximum: 2 description: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far tools: type: array items: $ref: "#/components/schemas/ChatCompletionTool" description: A list of tools the model may call enable_think: type: boolean description: Whether to enable thinking mode for the model default: true reasoning_format: type: string enum: [none, deepseek, deepseek-legacy, auto] description: Where to put the model's chain-of-thought. `none` keeps it inline in `message.content`; `deepseek` (default), `deepseek-legacy`, and `auto` move it to `message.reasoning_content`. default: deepseek top_k: type: integer minimum: 0 description: An alternative to sampling with temperature, called top-k sampling min_p: type: number format: float minimum: 0 maximum: 1 description: An alternative to sampling with temperature, called nucleus sampling repetition_penalty: type: number format: float minimum: 0 maximum: 100 description: The parameter for repetition penalty. 1.0 means no penalty grammar_string: type: string description: Inline GBNF grammar for constrained generation. ngl: type: integer description: Number of GPU/NPU layers to offload (llama_cpp only). Omit to use the server default set via `geniex serve --ngl` / `GENIEX_NGL` (999 out of the box); the server chooses the correct layout per backend. compute: type: string enum: [cpu, gpu, npu, hybrid] description: Compute unit to run on. Omit to use the server default set via `geniex serve --compute` / `GENIEX_COMPUTE`. QAIRT is NPU-only; other aliases are coerced with a warning. power_mode: type: string enum: [low_power_saver, power_saver, high_power_saver, low_balanced, balanced, high_performance, sustained_high_performance, burst, default] description: HTP power/clock-management mode, shared by qairt and llama_cpp. Omit to use the server default set via `geniex serve --power-mode` / `GENIEX_POWER_MODE` (burst out of the box). spec_type: type: string enum: ["", draft-mtp, draft-eagle3, draft-simple, ngram-simple, ngram-map-k, ngram-map-k4v, ngram-mod, ngram-cache] description: Speculative decoding type (llama_cpp only). Omit to use the `geniex serve --spec-type` default (disabled out of the box); set to empty to disable for this request. `draft-*` variants require `spec_draft_model`; `ngram-*` variants are self-speculative. spec_draft_model: type: string description: Draft/MTP model for `draft-*` spec types (llama_cpp only). Omit to use the `geniex serve --draft-model` default. Catalogue name `org/repo[:precision]` (must be pulled via `geniex pull` beforehand — the server does NOT auto-download) or absolute path to a local GGUF file. spec_n_max: type: integer minimum: 0 description: Max draft tokens per verification step (llama_cpp only). Omit to use the `geniex serve --draft-tokens` default (0 out of the box, which means the plugin default of 3). spec_n_min: type: integer minimum: 0 description: Min draft tokens per verification step (llama_cpp only). Omit to use the `geniex serve --draft-min` default; 0 = llama.cpp default. spec_p_min: type: number format: float minimum: 0 maximum: 1 description: Min greedy draft probability (llama_cpp only). Omit to use the `geniex serve --draft-p-min` default; 0 = llama.cpp default. ChatMessage: type: object required: [role, content] default: { "role": "user", "content": "Hello! Briefly introduce yourself." } properties: role: type: string enum: [system, user, assistant, tool] description: The role of the author of this message content: oneOf: - type: string - type: array items: $ref: "#/components/schemas/ChatMessageContent" description: The contents of the message reasoning_content: type: string description: The model's chain-of-thought, present on assistant responses when the effective `reasoning_format` is a separating value (e.g. the default `deepseek`). name: type: string description: The name of the author of this message tool_calls: type: array items: $ref: "#/components/schemas/ChatCompletionMessageToolCall" description: The tool calls generated by the model function_call: $ref: "#/components/schemas/ChatCompletionMessageFunctionCall" description: Deprecated and replaced by tool_calls ChatMessageContent: type: object properties: type: type: string enum: [text, image_url, input_audio] text: type: string image_url: $ref: "#/components/schemas/ChatMessageImageURL" input_audio: $ref: "#/components/schemas/ChatMessageAudioURL" ChatMessageImageURL: type: object properties: url: type: string detail: type: string enum: [low, high, auto] ChatMessageAudioURL: type: object properties: data: type: string description: The audio data (base64 encoded or URL) ChatCompletionTool: type: object properties: type: type: string enum: [function] function: $ref: "#/components/schemas/ChatCompletionToolFunction" ChatCompletionToolFunction: type: object required: [name] properties: name: type: string description: The name of the function to be called description: type: string description: A description of what the function does parameters: type: object description: The parameters the functions accepts ChatCompletionToolChoice: type: object properties: type: type: string enum: [function] function: type: object properties: name: type: string ChatCompletionMessageToolCall: type: object properties: id: type: string description: The ID of the tool call type: type: string enum: [function] description: The type of the tool function: $ref: "#/components/schemas/ChatCompletionMessageToolCallFunction" ChatCompletionMessageToolCallFunction: type: object properties: name: type: string description: The name of the function to call arguments: type: string description: The arguments to call the function with, as generated by the model in JSON format ChatCompletionMessageFunctionCall: type: object properties: name: type: string description: The name of the function to call arguments: type: string description: The arguments to call the function with, as generated by the model in JSON format ChatCompletionResponse: type: object required: [choices] properties: id: type: string description: A unique identifier for the chat completion object: type: string description: The object type, which is always "chat.completion" created: type: integer description: The Unix timestamp (in seconds) of when the chat completion was created model: type: string description: The model used for the chat completion choices: type: array items: $ref: "#/components/schemas/ChatChoice" description: A list of chat completion choices usage: $ref: "#/components/schemas/TokenUsage" ChatChoice: type: object properties: index: type: integer description: The index of the choice in the list of choices message: $ref: "#/components/schemas/ChatMessage" description: A chat completion message generated by the model finish_reason: type: string enum: [stop, length, tool_calls, content_filter, function_call] description: The reason the model stopped generating tokens logprobs: $ref: "#/components/schemas/ChatCompletionChoiceLogprobs" ChatCompletionChoiceLogprobs: type: object properties: content: type: array items: $ref: "#/components/schemas/ChatCompletionTokenLogprob" ChatCompletionTokenLogprob: type: object properties: token: type: string logprob: type: number bytes: type: array items: type: integer top_logprobs: type: array items: $ref: "#/components/schemas/ChatCompletionTokenLogprobTopLogprob" ChatCompletionTokenLogprobTopLogprob: type: object properties: token: type: string logprob: type: number bytes: type: array items: type: integer # ---------- Common ---------- ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong TokenUsage: type: object properties: prompt_tokens: type: integer description: Number of tokens in the prompt prompt_tokens_details: type: object properties: cached_tokens: type: integer description: Number of prompt tokens reused from the KV cache completion_tokens: type: integer description: Number of tokens in the generated completion total_tokens: type: integer description: Total number of tokens used in the request # ---------- Models ---------- ModelsListResponse: type: object properties: object: type: string description: The object type, which is always "list" data: type: array items: $ref: "#/components/schemas/Model" ModelResponse: type: object properties: id: type: string description: The model identifier model_type: type: string enum: [llm, vlm] description: GenieX extension — the model's type, so clients need no local model store object: type: string description: The object type, which is always "model" owned_by: type: string description: The organization that owns the model created: type: integer description: The Unix timestamp (in seconds) of when the model was created permission: type: array items: type: object description: The permissions associated with the model Model: type: object properties: id: type: string description: The model identifier owned_by: type: string description: The organization that owns the model