---
title: "Create Completion"
method: POST
path: "/api/v1/completions"
tags: ["Completions"]
---

# Create Completion

`POST /api/v1/completions`

Generate a text completion. Set `stream: true` for SSE streaming.

All SSE frames use `event: stream_event` with a JSON-serialized StreamEvent
payload. StreamEvent types: stream_start, text_start, text_delta, text_end,
tool_call_start, tool_call_delta, tool_call_end, finish, error.

## Request body

- CreateCompletionRequest
  - `messages` CompletionMessage[], required — The conversation messages.
    - `role` 'system' | 'user' | 'assistant' | 'tool' | 'developer', required — The role of the message author.
    - `content` CompletionContentPart[], required — Content parts of the message.
      - `kind` string, required — Content part type: text, image, tool_call, tool_result, thinking, etc.
      - `data` unknown
    - `name` string — Optional name for the message author.
    - `tool_call_id` string — Tool call ID for tool result messages.
  - `model` string — Model ID or alias. Server picks a ready-provider default if omitted.
  - `system` string — System prompt (convenience; prepended as a system message).
  - `stream` boolean — Stream response via SSE.
  - `tools` CompletionToolDefinition[] — Tool definitions available to the model.
    - `name` string, required — Tool name.
    - `description` string, required — Human-readable tool description.
    - `parameters` unknown, required
  - `tool_choice` CompletionToolChoice — Controls how the model selects tools.
    - `mode` 'auto' | 'none' | 'required' | 'named', required — Tool selection mode.
    - `tool_name` string — Required when mode is "named".
  - `schema` unknown
  - `temperature` number, double
  - `max_tokens` integer
  - `top_p` number, double
  - `stop_sequences` string[] — Stop sequences.
  - `reasoning_effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max' — Native reasoning-effort level requested for an LLM call.
  - `provider` string — Optional provider pin.
  - `provider_options` unknown

## Response `200`

Completion result (JSON when stream=false, SSE when stream=true)

- CompletionResponse
  - `id` string, required
  - `model` string, required — Canonical model ID selected for the request.
  - `provider` string, required — LLM provider identifier.
  - `message` CompletionMessage, required — A message in the conversation.
    - `role` 'system' | 'user' | 'assistant' | 'tool' | 'developer', required — The role of the message author.
    - `content` CompletionContentPart[], required — Content parts of the message.
      - `kind` string, required — Content part type: text, image, tool_call, tool_result, thinking, etc.
      - `data` unknown
    - `name` string — Optional name for the message author.
    - `tool_call_id` string — Tool call ID for tool result messages.
  - `stop_reason` string, required — Why generation stopped (end_turn, max_tokens, tool_calls).
  - `usage` CompletionUsage, required — Five disjoint token buckets for one completion. `input_tokens` excludes cache reads and writes, while `output_tokens` excludes reasoning tokens when the provider reports them separately.
    - `input_tokens` integer, required — Number of uncached input tokens consumed.
    - `output_tokens` integer, required — Number of non-reasoning output tokens generated.
    - `reasoning_tokens` integer, required — Number of separately reported reasoning tokens.
    - `cache_read_tokens` integer, required — Number of input tokens served from a provider cache.
    - `cache_write_tokens` integer, required — Number of input tokens written to a provider cache.
  - `output` unknown
  - `cost_usd` number, double — USD cost of the completion when known: estimated from catalog prices unless the provider returned authoritative billing data.
  - `cost_source` 'authoritative' | 'estimated' — Whether `cost_usd` came from provider billing data (authoritative) or catalog price estimation (estimated).

## Other responses

- `400` — Invalid request

---

[API](https://skmtc.net/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.net/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fabro-sh/fabro-run-api/revisions/64a24779d395/schema)