Sign in
Completions

Create Completion

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

All SSE frames use event: stream_event with a JSON-serialized lithos StreamEvent payload, discriminated by type: started, content_block_start, text_delta, reasoning_delta, tool_call_delta, content_block_end, usage, rate_limits, ended, and error.

post/api/v1/completions

Request body

modelstring

Model selector: provider/model, a model id or alias, or a provider id. The server picks a ready-provider default when omitted.

providerstring

Optional provider pin for a bare model selector.

systemstring

System prompt (convenience; prepended as a system message).

streamboolean

Stream response via SSE.

{"stackTrail":"components:schemas:CreateCompletionRequest:properties:schema","oasType":"schema","type":"unknown","description":"JSON Schema for structured output. Forces a non-streaming response whose `output` is the parsed object."}
max_output_tokensinteger
temperaturenumber double
top_pnumber double
stop_sequencesstring[]

Stop sequences.

reasoning_effort'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'

Native reasoning-effort level requested for an LLM call.

speed'fast' | 'balanced' | 'economical'

lithos Speed: the requested latency or cost tier.

metadataobject

Request tags forwarded to providers that accept them.

provider_optionsobject

Raw provider options keyed by provider id.

Response

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

{"stackTrail":"components:schemas:CompletionResponse:properties:output","oasType":"schema","type":"unknown","description":"Parsed structured output when `schema` was provided."}
idstring nullable
suppressed_tool_callsobject[]

Tool calls withheld because the turn ended early.

finish_reasonstring required

Why generation stopped: stop, length, tool_call, content_filter, error, incomplete, or a provider-specific reason.

rate_limitsobject
{"stackTrail":"components:schemas:CompletionResponse:properties:raw","oasType":"schema","type":"unknown","description":"The provider's success payload, when available."}

Example response

{
  "model": {
    "provider": "anthropic"
  }
}

Changes