Inference API schema — Kiln Documentation

Canonical field-level wire contract for POST /v1/chat/completions, POST /v1/completions, and POST /v1/completions/batch. Request objects explicitly identify Kiln's OpenAI-compatibility policy for unknown inputs; response objects describe only fields Kiln emits. Arbitrary JSON remains deliberate only for OpenAI tool definitions, tool choices, calls, and chat-template extension values.

Schema identity

Property	Value
Title	Kiln inference API contract v1
`$id`	`https://ericflo.github.io/kiln/contracts/kiln-inference-v1.schema.json`
Dialect	`https://json-schema.org/draft/2020-12/schema`
Root type	Union of 6 public entrypoints
Root object	Defined by the selected entrypoint

Entrypoints

Choose the request or response shape for the operation you are implementing. Each name links to its complete field table and constraints.

Entrypoint	Purpose	Shape	Unknown fields
`BatchCompletionRequest`	Generate one or more choices for each conversation in a batch.	23 fields	Unknown fields accepted and ignored
`BatchCompletionResponse`	All choices, token usage, and request-wide metadata from a batch generation request.	7 fields	Unknown fields rejected
`ChatCompletionRequest`	Create one or more OpenAI-compatible chat-completion choices.	29 fields	Unknown fields accepted and ignored
`ChatCompletionResponse`	A non-streaming OpenAI-compatible chat completion with Kiln metadata.	7 fields	Unknown fields rejected
`TextCompletionRequest`	Score prompt-token log probabilities through the compatibility completions endpoint.	7 fields	Unknown fields accepted and ignored
`TextCompletionResponse`	Prompt-token log probabilities, identity, and token usage for one scored prompt.	7 fields	Unknown fields rejected

Composition and conditional rules

Show exact composition rules

{
  "oneOf": [
    {
      "$ref": "#/$defs/BatchCompletionRequest"
    },
    {
      "$ref": "#/$defs/BatchCompletionResponse"
    },
    {
      "$ref": "#/$defs/ChatCompletionRequest"
    },
    {
      "$ref": "#/$defs/ChatCompletionResponse"
    },
    {
      "$ref": "#/$defs/TextCompletionRequest"
    },
    {
      "$ref": "#/$defs/TextCompletionResponse"
    }
  ]
}

Kiln contract annotations

Show exact Kiln annotations and examples

{
  "x-kiln-entrypoints": [
    "BatchCompletionRequest",
    "BatchCompletionResponse",
    "ChatCompletionChunkStream",
    "ChatCompletionRequest",
    "ChatCompletionResponse",
    "TextCompletionRequest",
    "TextCompletionResponse"
  ],
  "x-kiln-examples": {
    "BatchCompletionRequest": [
      {
        "prompts": [
          [
            {
              "role": "user",
              "content": "Name one primary color."
            }
          ],
          [
            {
              "role": "user",
              "content": "Name one secondary color."
            }
          ]
        ],
        "n": 2,
        "max_tokens": 16,
        "thinking_budget_tokens": null
      },
      {
        "prompts": [
          [
            {
              "role": "user",
              "content": "Name one color."
            }
          ]
        ],
        "adapter": null,
        "adapters": [
          {
            "name": "style",
            "scale": 1
          }
        ]
      }
    ],
    "BatchCompletionResponse": [
      {
        "id": "batchcmpl-example",
        "object": "batch.completion",
        "created": 1700000000,
        "model": "example-model",
        "completions": [
          {
            "prompt_index": 0,
            "completion_index": 0,
            "text": "Red.",
            "finish_reason": "stop",
            "usage": {
              "prompt_tokens": 8,
              "completion_tokens": 2,
              "total_tokens": 10
            }
          }
        ],
        "usage": {
          "prompt_tokens": 8,
          "completion_tokens": 2,
          "total_tokens": 10
        },
        "metadata": {
          "thinking_budget": {
            "configured": false,
            "tokens_source": "unlimited",
            "time_source": "unlimited"
          }
        }
      }
    ],
    "ChatCompletionChunk": [
      {
        "id": "chatcmpl-example",
        "object": "chat.completion.chunk",
        "created": 1700000000,
        "model": "example-model",
        "choices": [
          {
            "index": 0,
            "delta": {
              "content": "Blue"
            }
          }
        ]
      }
    ],
    "ChatCompletionRequest": [
      {
        "messages": [
          {
            "role": "user",
            "content": "What is 2 + 2?"
          }
        ],
        "max_tokens": 64,
        "thinking_budget_tokens": 32,
        "thinking_budget_ms": null,
        "stream": false
      },
      {
        "messages": [
          {
            "role": "user",
            "content": "What is 3 + 3?"
          }
        ],
        "adapter": "math",
        "adapters": null
      }
    ],
    "ChatCompletionResponse": [
      {
        "id": "chatcmpl-example",
        "object": "chat.completion",
        "created": 1700000000,
        "model": "example-model",
        "choices": [
          {
            "index": 0,
            "message": {
              "role": "assistant",
              "content": "4"
            },
            "finish_reason": "stop"
          }
        ],
        "usage": {
          "prompt_tokens": 12,
          "completion_tokens": 1,
          "total_tokens": 13
        },
        "metadata": {
          "thinking_enabled": false,
          "thinking_mode": "non_reasoning",
          "thinking_source": "template_default",
          "final_content_empty": false,
          "reasoning_folded_into_content": false,
          "thinking_budget": {
            "configured": false,
            "applied": false,
            "tokens_source": "unlimited",
            "time_source": "unlimited",
            "triggered": false
          }
        }
      }
    ],
    "RolloutProvenanceV1": [
      {
        "schema": "kiln.rollout-provenance.v1",
        "input_token_ids": [
          1,
          2
        ],
        "prompt_token_count": 1,
        "prompt_messages_sha256": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "scored_payload_sha256": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "action_tokens": [
          {
            "sequence_index": 1,
            "token_id": 2,
            "source": "sampled",
            "behavior_logprob": -0.25
          }
        ],
        "behavior_policy": {
          "served_model_id": "example-model",
          "base_model_sha256": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
          "inference_config_sha256": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
          "implementation": "kiln"
        },
        "tokenizer": {
          "vocab_sha256": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
          "config_sha256": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
          "chat_template_sha256": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
        },
        "sampling": {
          "temperature": 0.9,
          "top_p": 0.95,
          "top_k": 20,
          "min_p": 0,
          "max_tokens": 64,
          "repetition_penalty": 1,
          "presence_penalty": 0,
          "frequency_penalty": 0,
          "stop": []
        },
        "seed": 42,
        "generation_backend": "rocm"
      }
    ],
    "StreamingTokenTiming": [
      {
        "object": "kiln.token_timing",
        "source": "batching_engine",
        "token_index": 0,
        "token_id": 42,
        "ready_ms": 12.5,
        "producer_delivered_ms": 12.6,
        "handler_received_ms": 12.8,
        "body_enqueued_ms": 13,
        "response_delivery_ms": 0.1,
        "handler_queue_ms": 0.2,
        "queue_delay_ms": 0.3,
        "client_delivery_ms": 0.2,
        "blocking_phase": null,
        "blocking_phase_ms": null
      }
    ],
    "TextCompletionRequest": [
      {
        "prompt": [
          1,
          42,
          314
        ],
        "max_tokens": 0,
        "prompt_logprobs": 5,
        "add_special_tokens": true
      }
    ],
    "TextCompletionResponse": [
      {
        "id": "cmpl-example",
        "object": "text_completion",
        "created": 1700000000,
        "model": "example-model",
        "system_fingerprint": null,
        "choices": [
          {
            "index": 0,
            "text": "",
            "finish_reason": "length",
            "prompt_logprobs": [
              null,
              {
                "42": {
                  "logprob": -0.25,
                  "rank": 1,
                  "decoded_token": "answer"
                }
              }
            ]
          }
        ],
        "usage": {
          "prompt_tokens": 3,
          "completion_tokens": 0,
          "total_tokens": 3
        }
      }
    ]
  },
  "x-kiln-field-schema-status": "complete"
}

Definitions

AdapterRefOne saved adapter and its composition scale.2 fields

Type: object.

Field	Required	Type	Constraints and default	Description
`name`	yes	`string`	minimum length 1	Saved adapter name. The runtime also rejects path separators, traversal, and absolute paths.
`scale`	yes	`number`	-	Composition scale used when merging request-wide adapters. The request must contain a finite JSON number; Kiln applies no narrower range.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "AdapterRef",
  "x-kiln-unknown-field-policy": "accepted_and_ignored"
}

BatchCompletionItemOne generated choice from one prompt in a batch request.8 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`prompt_index`	yes	`integer`	minimum 0	Zero-based index into request.prompts.
`completion_index`	yes	`integer`	minimum 0	Zero-based choice index for this prompt.
`text`	yes	`string`	-	Final answer content after separated reasoning.
`reasoning_content`	no	`string`	-	Reasoning text inside the model's thinking block; omitted when absent.
`tool_calls`	no	`ToolCallArray`	-	OpenAI-shaped tool calls; omitted when absent.
`finish_reason`	yes	`FinishReason`	-	Finish reason. Why generation ended. `error` identifies a per-item batch failure; ordinary termination emits `stop`, `length`, or `tool_calls`.
`thinking_budget`	no	`outcome`	-	Completion-specific terminal thinking-budget outcome; omitted when no budget applied.
`usage`	yes	`Usage`	-	Usage. Prompt, completion, and total token counts.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "BatchCompletionItem"
}

BatchCompletionMetadataRequest-wide metadata for a completed batch response.1 field

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`thinking_budget`	yes	`ThinkingBudgetConfigurationMetadata`	-	Resolved request-wide thinking-limit configuration.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "BatchCompletionMetadata"
}

BatchCompletionRequestGenerate one or more choices for each conversation in a batch.23 fields

Type: object.

Field	Required	Type	Constraints and default	Description
`model`	no	`NullableString`	-	Served model ID. Missing or null selects the configured served_model_id.
`prompts`	yes	`array<array<ChatMessageInput>>`	minimum items 1; maximum items 64	One message array per prompt. prompts.length multiplied by n must not exceed 64 outputs.
`n`	no	`null \| integer`	default 1	Completions per prompt. Missing or null means 1.
`temperature`	no	`NullableSamplingNumber`	-	Sampling temperature. Null uses the selected preset or runtime default.
`top_p`	no	`NullableSamplingNumber`	-	Nucleus-sampling probability mass. Null uses the selected preset or runtime default.
`top_k`	no	`NullableUint32`	-	Maximum candidate count for top-k filtering. Null uses the selected preset or runtime default.
`min_p`	no	`NullableSamplingNumber`	-	Minimum probability relative to the most likely token. Null uses the selected preset or runtime default.
`presence_penalty`	no	`NullableSamplingNumber`	-	OpenAI-style presence penalty. Null uses the selected preset or runtime default.
`frequency_penalty`	no	`NullableSamplingNumber`	-	OpenAI-style frequency penalty. Null uses the selected preset or runtime default.
`repetition_penalty`	no	`NullableSamplingNumber`	-	Token repetition penalty. Null uses the selected preset or runtime default.
`sampling_preset`	no	`SamplingPreset`	-	Named group of sampling defaults; explicit sampling fields take precedence.
`max_tokens`	no	`NullableNonNegativeInteger`	-	Maximum generated tokens per completion. Null uses the runtime default.
`max_completion_tokens`	no	`NullableNonNegativeInteger`	-	Newer OpenAI alias. max_tokens wins when both are non-null.
`ignore_eos`	no	`boolean`	default false	Treat tokenizer EOS IDs as ordinary tokens; max_tokens and explicit stop sequences still bound generation.
`thinking_budget_tokens`	no	`limitOverride`	-	Per-request thinking-token limit override; null explicitly removes the limit.
`thinking_budget_ms`	no	`limitOverride`	-	Per-request thinking-time limit in milliseconds; null explicitly removes the limit.
`stop`	no	`StopInput`	-	One or more decoded-text stop sequences.
`seed`	no	`NullableUint64`	-	Request seed; null lets the runtime choose.
`adapter`	no	`NullableString`	-	One adapter applied to every prompt. Mutually exclusive with adapters.
`adapters`	no	`null \| array<AdapterRef>`	-	Request-wide adapter composition. Mutually exclusive with adapter.
`tools`	no	`NullableToolArray`	-	Request-wide OpenAI-shaped tool definitions forwarded to the chat template.
`tool_choice`	no	`any`	-	Opaque OpenAI tool_choice value forwarded to the chat template.
`chat_template_kwargs`	no	`NullableTemplateKwargs`	-	Request-wide keyword arguments forwarded to the chat template.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "allOf": [
    {
      "not": {
        "required": [
          "adapter",
          "adapters"
        ],
        "properties": {
          "adapter": {
            "type": "string"
          },
          "adapters": {
            "type": "array"
          }
        }
      }
    }
  ]
}

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-field-schema-status": "complete",
  "x-kiln-rust-type": "BatchCompletionRequest",
  "x-kiln-semantic-constraints": [
    "prompts.length * (n or 1) <= 64",
    "the effective max_tokens must fit the active tokenizer's reasoning close sequence when a thinking budget applies"
  ],
  "x-kiln-unknown-field-policy": "accepted_and_ignored"
}

BatchCompletionResponseAll choices, token usage, and request-wide metadata from a batch generation request.7 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`id`	yes	`string`	pattern ^batchcmpl-	Unique batch-completion identifier.
`object`	yes	`any`	const "batch.completion"	OpenAI-style object discriminator for a batch completion.
`created`	yes	`UnixSeconds`	-	Created. Whole seconds since the Unix epoch.
`model`	yes	`string`	-	Served model ID used for every completion.
`completions`	yes	`array<BatchCompletionItem>`	minimum items 1; maximum items 64	Generated choices in prompt order, then completion order.
`usage`	yes	`Usage`	-	Usage. Prompt, completion, and total token counts.
`metadata`	yes	`BatchCompletionMetadata`	-	Metadata. Request-wide metadata for a completed batch response.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-field-schema-status": "complete",
  "x-kiln-rust-type": "BatchCompletionResponse"
}

ChatCompletionChunkOne OpenAI-compatible server-sent event in a streaming chat completion.7 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`id`	yes	`string`	pattern ^chatcmpl-	Chat-completion identifier shared by every chunk in the stream.
`object`	yes	`any`	const "chat.completion.chunk"	OpenAI-compatible streaming-chunk discriminator.
`created`	yes	`UnixSeconds`	-	Created. Whole seconds since the Unix epoch.
`model`	yes	`string`	-	Served model ID used for this completion.
`choices`	yes	`array<ChunkChoice>`	-	Incremental choices carried by this chunk; the usage-only chunk has none.
`metadata`	no	`StreamingTerminalMetadata`	-	Metadata. Metadata attached only to the terminal finish chunk.
`usage`	no	`Usage`	-	Token counts for this individual completion.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "ChatCompletionChunk"
}

ChatCompletionChunkStreamServer-sent event stream containing JSON `ChatCompletionChunk` events, optional `kiln.token_timing` events when `include_performance` is true, an optional usage chunk with no choices when `stream_options.include_usage` is true, and a final `data: [DONE]` sentinel. The terminal finish chunk carries thinking-budget metadata before the optional usage chunk and sentinel.0 fields

Type: string. Constraints: content media type text/event-stream.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-event-schemas": [
    {
      "$ref": "#/$defs/ChatCompletionChunk"
    },
    {
      "$ref": "#/$defs/StreamingTokenTiming"
    }
  ],
  "x-kiln-field-schema-status": "complete",
  "x-kiln-rust-type": "ChatCompletionChunkStream"
}

ChatCompletionMetadataKiln-specific thinking, configuration, and performance metadata for a chat completion.10 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`thinking_enabled`	yes	`boolean`	-	Whether the rendered prompt enabled model thinking.
`thinking_mode`	yes	`string`	enum "non_reasoning", "reasoning"	Mode observed from the rendered prompt.
`thinking_source`	yes	`string`	enum "custom", "request", "server_default", "template_default"	Authority that selected the effective thinking mode.
`default_thinking_enabled`	no	`boolean`	-	Configured server or template default before a request override.
`final_content_empty`	yes	`boolean`	-	Whether the final answer content is empty after reasoning separation.
`content_empty_reason`	no	`string`	enum "no_content", "reasoning_without_final_content", "tool_call"	Reason final answer content is empty; omitted when content is present.
`reasoning_folded_into_content`	yes	`boolean`	-	Whether compatibility mode copied separated reasoning into content.
`thinking_budget`	yes	`record`	-	Resolved and terminal thinking-budget record.
`config_hashes`	no	`ConfigHashes`	-	Configuration hashes when requested or enabled by default.
`performance`	no	`ChatCompletionPerformanceMetadata`	-	Request-local performance metadata when requested or enabled by default.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "ChatCompletionMetadata"
}

ChatCompletionPerformanceMetadataToken counts and request-local latency measurements emitted when performance metadata is enabled.15 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`prompt_tokens`	yes	`NonNegativeInteger`	-	Number of prompt tokens processed.
`completion_tokens`	yes	`NonNegativeInteger`	-	Number of generated tokens.
`ttft_ms`	yes	`NullableNonNegativeNumber`	-	Time to first generated token in milliseconds, or null when unavailable.
`prefill_ms`	yes	`NullableNonNegativeNumber`	-	Measured prompt-prefill work in milliseconds, or null when unavailable.
`actor_queue_ms`	yes	`NullableNonNegativeNumber`	-	Time waiting in the batching actor's queue, or null off the actor path.
`actor_admission_ms`	yes	`NullableNonNegativeNumber`	-	Time from actor receipt to workload admission, or null off the actor path.
`actor_prefill_wall_ms`	yes	`NullableNonNegativeNumber`	-	Wall-clock time from actor admission through prompt prefill, or null off the actor path.
`resident_prefill_used`	yes	`NullableBoolean`	-	Whether prefill used resident recurrent state, or null when the route does not report it.
`decode_ms`	yes	`NullableNonNegativeNumber`	-	Measured token-decode work in milliseconds, or null when unavailable.
`total_latency_ms`	yes	`number`	minimum 0	Request latency from handler entry through response construction, in milliseconds.
`decode_tokens_per_sec`	yes	`NullableNonNegativeNumber`	-	Generated tokens divided by measured decode time, or null when unavailable.
`adapter_used`	yes	`string`	-	Base or named adapter selection used for generation.
`thinking_mode`	yes	`string`	-	Thinking mode observed from the rendered prompt.
`finish_reason`	yes	`FinishReason`	-	Terminal reason for this choice.
`latency`	yes	`RequestLatencyDiagnostics \| null`	-	Detailed latency diagnostics when the serving path recorded them; otherwise null.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "ChatCompletionPerformanceMetadata"
}

ChatCompletionRequestCreate one or more OpenAI-compatible chat-completion choices.29 fields

Type: object.

Field	Required	Type	Constraints and default	Description
`model`	no	`NullableString`	-	Served model ID. Missing or null selects the configured served_model_id.
`messages`	yes	`array<ChatMessageInput>`	-	Conversation messages in template order.
`n`	no	`null \| integer`	default 1	Number of choices. Values above 1 require stream=false.
`temperature`	no	`NullableSamplingNumber`	-	Sampling temperature. Null uses the selected preset or runtime default.
`top_p`	no	`NullableSamplingNumber`	-	Nucleus-sampling probability mass. Null uses the selected preset or runtime default.
`top_k`	no	`NullableUint32`	-	Maximum candidate count for top-k filtering. Null uses the selected preset or runtime default.
`min_p`	no	`NullableSamplingNumber`	-	Minimum probability relative to the most likely token. Null uses the selected preset or runtime default.
`presence_penalty`	no	`NullableSamplingNumber`	-	OpenAI-style presence penalty. Null uses the selected preset or runtime default.
`frequency_penalty`	no	`NullableSamplingNumber`	-	OpenAI-style frequency penalty. Null uses the selected preset or runtime default.
`repetition_penalty`	no	`NullableSamplingNumber`	-	Token repetition penalty. Null uses the selected preset or runtime default.
`sampling_preset`	no	`SamplingPreset`	-	Named group of sampling defaults; explicit sampling fields take precedence.
`max_tokens`	no	`NullableNonNegativeInteger`	-	Maximum generated tokens per choice. Null uses the runtime default.
`max_completion_tokens`	no	`NullableNonNegativeInteger`	-	Newer OpenAI alias. max_tokens wins when both are non-null.
`ignore_eos`	no	`boolean`	default false	Treat tokenizer EOS IDs as ordinary tokens; incompatible with rollout_provenance=true.
`thinking_budget_tokens`	no	`limitOverride`	-	Per-request thinking-token limit override; null explicitly removes the limit.
`thinking_budget_ms`	no	`limitOverride`	-	Per-request thinking-time limit in milliseconds; null explicitly removes the limit.
`stream`	no	`boolean`	default false	Return server-sent events instead of one JSON response.
`stream_options`	no	`null \| StreamOptions`	-	Additional streaming behavior; ignored for a non-streaming request.
`stop`	no	`StopInput`	-	One or more decoded-text stop sequences.
`seed`	no	`NullableUint64`	-	Request seed; null lets the runtime choose.
`adapter`	no	`NullableString`	-	Missing uses the server default; null or an empty string selects base; a non-empty string selects a named adapter. Mutually exclusive with adapters.
`adapters`	no	`null \| array<AdapterRef>`	-	Per-request adapter composition. Mutually exclusive with adapter.
`tools`	no	`NullableToolArray`	-	OpenAI-shaped tool definitions forwarded to the chat template.
`tool_choice`	no	`any`	-	Opaque OpenAI tool_choice value forwarded to the chat template.
`chat_template_kwargs`	no	`NullableTemplateKwargs`	-	Keyword arguments forwarded to the chat template.
`fold_reasoning_into_content`	no	`NullableBoolean`	-	Override whether separated reasoning is also copied into final content.
`include_performance`	no	`NullableBoolean`	-	Override whether the response includes request-local performance metadata.
`include_config_hashes`	no	`NullableBoolean`	-	Override whether the response includes content hashes for the active configuration.
`rollout_provenance`	no	`boolean`	default false	Emit exact behavior-policy provenance. Requires one non-streaming real batched choice, ignore_eos=false, no non-empty tools or tool_choice, and positive effective generation capacity.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "allOf": [
    {
      "not": {
        "required": [
          "adapter",
          "adapters"
        ],
        "properties": {
          "adapters": {
            "type": "array"
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "stream"
        ],
        "properties": {
          "stream": {
            "const": true
          }
        }
      },
      "then": {
        "not": {
          "required": [
            "n"
          ],
          "properties": {
            "n": {
              "type": "integer",
              "minimum": 2
            }
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "rollout_provenance"
        ],
        "properties": {
          "rollout_provenance": {
            "const": true
          }
        }
      },
      "then": {
        "properties": {
          "ignore_eos": {
            "const": false
          },
          "stream": {
            "const": false
          },
          "n": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "const": 1
              }
            ]
          },
          "max_tokens": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "integer",
                "minimum": 1
              }
            ]
          }
        }
      }
    }
  ]
}

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-field-schema-status": "complete",
  "x-kiln-rust-type": "ChatCompletionRequest",
  "x-kiln-semantic-constraints": [
    "rollout_provenance=true requires the real batching engine and content-addressed base-policy identity",
    "rollout_provenance=true rejects non-empty tools and non-null tool_choice",
    "the effective max_tokens must fit the active tokenizer's reasoning close sequence when a thinking budget applies"
  ],
  "x-kiln-unknown-field-policy": "accepted_and_ignored"
}

ChatCompletionResponseA non-streaming OpenAI-compatible chat completion with Kiln metadata.7 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`id`	yes	`string`	pattern ^chatcmpl-	Unique chat-completion identifier.
`object`	yes	`any`	const "chat.completion"	OpenAI-compatible object discriminator.
`created`	yes	`UnixSeconds`	-	Created. Whole seconds since the Unix epoch.
`model`	yes	`string`	-	Served model ID used for generation.
`choices`	yes	`array<Choice>`	minimum items 1; maximum items 64	Generated choices in index order.
`usage`	yes	`Usage`	-	Usage. Prompt, completion, and total token counts.
`metadata`	yes	`ChatCompletionMetadata`	-	Metadata. Kiln-specific thinking, configuration, and performance metadata for a chat completion.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-field-schema-status": "complete",
  "x-kiln-rust-type": "ChatCompletionResponse"
}

ChatMessageInputOne input message passed to the model's chat template.6 fields

Type: object.

Field	Required	Type	Constraints and default	Description
`role`	yes	`string`	-	Template-visible role. Kiln forwards the string rather than enforcing a fixed vocabulary.
`content`	no	`null \| string \| array<any>`	default ""	String, null, or OpenAI content-part array. Text/input_text/output_text parts are concatenated and non-text parts are ignored.
`reasoning_content`	no	`NullableString`	-	Prior assistant reasoning preserved for template round trips.
`tool_calls`	no	`null \| ToolCallArray`	-	Prior assistant tool calls preserved for the next template render.
`name`	no	`NullableString`	-	Optional message name.
`tool_call_id`	no	`NullableString`	-	Tool-call identifier associated with a tool response.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "Message",
  "x-kiln-unknown-field-policy": "accepted_and_ignored"
}

ChatMessageOutputOne assistant message emitted in a non-streaming choice.6 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`role`	yes	`string`	-	Assistant message role.
`content`	yes	`string`	-	Final answer content after reasoning separation.
`reasoning_content`	no	`string`	-	Separated reasoning content; omitted when absent.
`tool_calls`	no	`ToolCallArray`	-	Tool calls emitted by the assistant; omitted when absent.
`name`	no	`string`	-	Optional message name.
`tool_call_id`	no	`string`	-	Tool-call identifier associated with a tool response.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "Message"
}

ChoiceOne complete non-streaming chat choice.5 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`index`	yes	`NonNegativeInteger`	-	Zero-based choice index.
`message`	yes	`ChatMessageOutput`	-	Complete assistant message for this choice.
`finish_reason`	yes	`FinishReason`	-	Why generation ended for this choice.
`thinking_budget`	no	`outcome`	-	Thinking budget. See thinking-budget-v1.schema.json#/$defs/outcome.
`rollout_provenance`	no	`RolloutProvenanceV1`	-	Exact behavior-policy provenance when requested.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "Choice"
}

ChunkChoiceOne incremental choice in a streaming chat chunk.3 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`index`	yes	`NonNegativeInteger`	-	Zero-based choice index.
`delta`	yes	`Delta`	-	Fields added by this streaming chunk.
`finish_reason`	no	`FinishReason`	-	Why generation ended; present only on the terminal chunk.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "ChunkChoice"
}

ConfigHashesContent hashes that identify the tokenizer, templates, model configuration, and resolved inference configuration.5 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`tokenizer_config_hash`	no	`Sha256`	-	Hash of the tokenizer configuration.
`chat_template_hash`	no	`Sha256`	-	Hash of the inference chat template.
`training_chat_template_hash`	no	`Sha256`	-	Hash of the training chat template.
`model_config_hash`	no	`Sha256`	-	Hash of the model configuration.
`effective_config_hash`	no	`Sha256`	-	Hash of the resolved inference configuration.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "ConfigHashes"
}

DeltaIncremental message fields emitted in a streaming choice.4 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`role`	no	`string`	-	Role emitted when a streaming choice begins.
`content`	no	`string`	-	Incremental final-answer text.
`reasoning_content`	no	`string`	-	Incremental separated reasoning text.
`tool_calls`	no	`ToolCallArray`	-	Tool-call deltas emitted by this chunk.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "Delta"
}

FinishReasonWhy generation ended. `error` identifies a per-item batch failure; ordinary termination emits `stop`, `length`, or `tool_calls`.0 fields

Type: string. Constraints: enum "error", "length", "stop", "tool_calls".

LatencyPhaseTimingsBounded request phase timings; null means the serving path did not measure that subphase.20 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`actor_queue_ms`	yes	`NullableNonNegativeNumber`	-	Time waiting for the batching actor to receive the request.
`actor_admission_ms`	yes	`NullableNonNegativeNumber`	-	Time between actor receipt and workload admission.
`tokenization_ms`	yes	`NullableNonNegativeNumber`	-	Time spent rendering and tokenizing the prompt.
`prefill_ms`	yes	`NullableNonNegativeNumber`	-	Measured accelerator time spent processing prompt tokens.
`decode_ms`	yes	`NullableNonNegativeNumber`	-	Measured accelerator time spent generating tokens.
`actor_cycle_idle_ms`	yes	`NullableNonNegativeNumber`	-	Intentional batching-actor pacing time.
`sampling_ms`	yes	`NullableNonNegativeNumber`	-	Time spent selecting output tokens from logits.
`readback_ms`	yes	`NullableNonNegativeNumber`	-	Time spent transferring inference results to the host.
`response_delivery_ms`	yes	`NullableNonNegativeNumber`	-	Time from token readiness to producer handoff.
`handler_queue_ms`	yes	`NullableNonNegativeNumber`	-	Time from producer handoff to HTTP-handler receipt.
`client_delivery_ms`	yes	`NullableNonNegativeNumber`	-	Time from handler receipt to response-body enqueue.
`gpu_lock_wait_ms`	yes	`NullableNonNegativeNumber`	-	Time waiting for exclusive accelerator ownership.
`graph_capture_ms`	yes	`NullableNonNegativeNumber`	-	Time spent capturing an accelerator graph.
`graph_replay_ms`	yes	`NullableNonNegativeNumber`	-	Time spent submitting an accelerator graph replay.
`synchronization_ms`	yes	`NullableNonNegativeNumber`	-	Time spent waiting for accelerator synchronization.
`resize_ms`	yes	`NullableNonNegativeNumber`	-	Time spent resizing runtime-owned storage.
`trim_ms`	yes	`NullableNonNegativeNumber`	-	Time spent trimming or reclaiming runtime-owned storage.
`adapter_ms`	yes	`NullableNonNegativeNumber`	-	Time spent loading, composing, or applying an adapter.
`training_ms`	yes	`NullableNonNegativeNumber`	-	Time blocked by accelerator work owned by training.
`unexplained_ms`	yes	`NullableNonNegativeNumber`	-	Measured latency not covered by another reported phase.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "LatencyPhaseTimings"
}

LatencyStallReasonCountsNumber of retained inter-token stalls attributed to each bounded phase.19 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`actor_queue`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to batching-actor queueing.
`actor_admission`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to batching-actor admission.
`actor_prefill`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to another request's actor-owned prefill.
`actor_decode`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to actor-owned decode work.
`actor_cycle_idle`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to intentional actor pacing.
`response_delivery`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to producer handoff.
`handler_queue`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to the queue before the HTTP handler.
`client_delivery`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to response-body delivery.
`sampling`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to token sampling.
`readback`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to accelerator readback.
`gpu_lock_wait`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to accelerator-ownership waits.
`graph_capture`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to graph capture.
`graph_replay`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to graph replay.
`synchronization`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to accelerator synchronization.
`resize`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to storage resizing.
`trim`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to storage trimming or reclaim.
`adapter`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to adapter work.
`training`	yes	`NonNegativeInteger`	-	Stalls primarily attributed to training-owned accelerator work.
`unexplained`	yes	`NonNegativeInteger`	-	Stalls that no measured phase explains.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "LatencyStallReasonCounts"
}

NonNegativeIntegerAn integer greater than or equal to zero.0 fields

Type: integer. Constraints: minimum 0.

NullableBooleanA Boolean value or null.0 fields

Type: null | boolean.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "boolean"
    }
  ]
}

NullableNonNegativeIntegerA non-negative integer or null.0 fields

Type: null | NonNegativeInteger.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "$ref": "#/$defs/NonNegativeInteger"
    }
  ]
}

NullableNonNegativeNumberA non-negative finite JSON number or null.0 fields

Type: null | number.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "number",
      "minimum": 0
    }
  ]
}

NullableSamplingNumberFinite JSON number or null. The chat and batch endpoints currently apply no narrower range check before sampling.0 fields

Type: null | number.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "number"
    }
  ]
}

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-runtime-validation": "finite_json_number_only"
}

NullableStringA string or null.0 fields

Type: null | string.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "string"
    }
  ]
}

NullableTemplateKwargsTemplate-specific keyword arguments, or null.0 fields

Type: null | object.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "object",
      "additionalProperties": {},
      "description": "Template-specific JSON values, including enable_thinking."
    }
  ]
}

NullableToolArrayOpenAI-shaped tool definitions, or null.0 fields

Type: null | array<any>.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "array",
      "items": {},
      "description": "Opaque OpenAI tool definitions forwarded to the chat template."
    }
  ]
}

NullableUint32An unsigned 32-bit integer or null.0 fields

Type: null | integer.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "integer",
      "minimum": 0,
      "maximum": 4294967295
    }
  ]
}

NullableUint64An unsigned 64-bit integer or null.0 fields

Type: null | integer.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "integer",
      "minimum": 0,
      "maximum": 18446744073709552000
    }
  ]
}

PromptLogprobEntryThe log probability, rank, and decoded text for one candidate token.3 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`logprob`	yes	`number`	-	Natural-log probability assigned to this token.
`rank`	yes	`integer`	minimum 1	One-based vocabulary rank by log probability.
`decoded_token`	yes	`string`	-	Tokenizer-decoded text for this token ID.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "PromptLogprobEntry"
}

PromptLogprobMapMap from decimal token ID strings to the observed/top-K log-probability entry.0 fields

Type: object.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "propertyNames": {
    "pattern": "^[0-9]+$"
  },
  "additionalProperties": {
    "$ref": "#/$defs/PromptLogprobEntry"
  }
}

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "BTreeMap<String, PromptLogprobEntry>"
}

RequestLatencyDiagnosticsRequest-local TTFT, ITL tail, bounded stall reasons, and honest phase-coverage diagnostics.14 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`emitted_tokens`	yes	`NonNegativeInteger`	-	Number of generated tokens emitted by the request.
`gap_samples`	yes	`NonNegativeInteger`	-	Number of inter-token gaps observed.
`retained_gap_samples`	yes	`integer`	minimum 0; maximum 8192	Inter-token gaps retained for percentile calculation after the bounded sample cap.
`gap_samples_truncated`	yes	`boolean`	-	Whether the request produced more gap samples than the diagnostic retained.
`ttft_ms`	yes	`NullableNonNegativeNumber`	-	Time from request start to the first generated token.
`itl_ms_p50`	yes	`NullableNonNegativeNumber`	-	Median retained inter-token latency.
`itl_ms_p99`	yes	`NullableNonNegativeNumber`	-	99th-percentile retained inter-token latency.
`itl_ms_p999`	yes	`NullableNonNegativeNumber`	-	99.9th-percentile retained inter-token latency.
`max_itl_ms`	yes	`NullableNonNegativeNumber`	-	Largest observed inter-token latency.
`stall_threshold_ms`	yes	`NullableNonNegativeNumber`	-	Inter-token gap at or above which a sample is classified as a stall.
`stall_count`	yes	`NonNegativeInteger`	-	Number of inter-token gaps classified as stalls.
`unexplained_stall_count`	yes	`NonNegativeInteger`	-	Number of stalls not covered by a measured phase.
`stall_reasons`	yes	`LatencyStallReasonCounts`	-	Stall counts grouped by the phase with the largest overlap.
`phases`	yes	`LatencyPhaseTimings`	-	Measured request time grouped by bounded phase.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "RequestLatencyDiagnostics"
}

RolloutActionTokenV1One generated token labeled as sampled or forced, with the behavior-policy log probability present only for sampled tokens.0 fields

Type: object | object.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "object",
      "required": [
        "sequence_index",
        "token_id",
        "source",
        "behavior_logprob"
      ],
      "properties": {
        "sequence_index": {
          "$ref": "#/$defs/NonNegativeInteger"
        },
        "token_id": {
          "type": "integer",
          "minimum": 0,
          "maximum": 4294967295
        },
        "source": {
          "const": "sampled"
        },
        "behavior_logprob": {
          "type": "number",
          "maximum": 0.000001
        }
      },
      "additionalProperties": false
    },
    {
      "type": "object",
      "required": [
        "sequence_index",
        "token_id",
        "source",
        "behavior_logprob"
      ],
      "properties": {
        "sequence_index": {
          "$ref": "#/$defs/NonNegativeInteger"
        },
        "token_id": {
          "type": "integer",
          "minimum": 0,
          "maximum": 4294967295
        },
        "source": {
          "const": "forced"
        },
        "behavior_logprob": {
          "type": "null"
        }
      },
      "additionalProperties": false
    }
  ]
}

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "RolloutActionTokenV1"
}

RolloutAdapterIdentityV1The name and content hash of the adapter used for a rollout.2 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`name`	yes	`RolloutIdentityText`	-	Saved adapter name.
`content_sha256`	yes	`Sha256`	-	Content hash of the adapter used for generation.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "RolloutAdapterIdentityV1"
}

RolloutBehaviorPolicyIdentityV1Content-addressed identity of the model, adapter, configuration, and implementation that generated a rollout.5 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`served_model_id`	yes	`RolloutIdentityText`	-	Model ID exposed by the inference API.
`base_model_sha256`	yes	`Sha256`	-	Canonical content hash of the base model.
`adapter`	no	`RolloutAdapterIdentityV1`	-	Adapter identity when generation used one; omitted for base.
`inference_config_sha256`	yes	`Sha256`	-	Hash of the resolved inference policy.
`implementation`	yes	`RolloutIdentityText`	-	Implementation identity that generated the rollout.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "RolloutBehaviorPolicyIdentityV1"
}

RolloutChatTemplateInvocationV1Tool and template inputs that affected the rendered rollout prompt.3 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`tools`	no	`array<any>`	maximum items 256	Tool definitions supplied to the chat template.
`tool_choice`	no	`any`	-	OpenAI-shaped tool-choice value supplied to the chat template.
`template_kwargs`	no	`object`	maximum properties 256	Additional keyword arguments supplied to the chat template.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "RolloutChatTemplateInvocationV1",
  "x-kiln-semantic-constraints": [
    "serialized object size <= 1048576 bytes"
  ]
}

RolloutIdentityTextNon-empty, trimmed identity text without control characters. The schema's `maxLength` bounds code points; the runtime also rejects surrounding whitespace and enforces at most 256 UTF-8 bytes.0 fields

Type: string. Constraints: minimum length 1; maximum length 256; pattern ^[^\u0000-\u001f\u007f]+$.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-max-utf8-bytes": 256
}

RolloutProvenanceV1Exact prompt, action-token, behavior-policy, tokenizer, sampling, and backend evidence for one generated rollout.12 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`schema`	yes	`any`	const "kiln.rollout-provenance.v1"	Provenance schema identifier.
`input_token_ids`	yes	`array<integer>`	minimum items 1; maximum items 16777216	Rendered prompt tokens followed by every generated action token.
`prompt_token_count`	yes	`integer`	minimum 1	Number of leading input_token_ids that belong to the rendered prompt.
`prompt_messages_sha256`	yes	`Sha256`	-	Hash of the canonical input-message payload.
`scored_payload_sha256`	yes	`Sha256`	-	Hash of the exact token payload scored by the behavior policy.
`action_tokens`	yes	`array<RolloutActionTokenV1>`	minimum items 1	Ordered generated tokens with sampled-versus-forced provenance.
`behavior_policy`	yes	`RolloutBehaviorPolicyIdentityV1`	-	Content-addressed policy that generated the action tokens.
`tokenizer`	yes	`RolloutTokenizerIdentityV1`	-	Content-addressed tokenizer used for prompt rendering and generation.
`template_invocation`	no	`RolloutChatTemplateInvocationV1`	-	Tool and template arguments that affected prompt rendering; omitted when empty.
`sampling`	yes	`RolloutSamplingConfigV1`	-	Resolved sampling configuration used for generation.
`seed`	yes	`integer`	minimum 0; maximum 18446744073709552000	Resolved generation seed.
`generation_backend`	yes	`string`	minimum length 1; maximum length 64; pattern ^[^\u0000-\u001f\u007f]+$	Backend name that generated the rollout.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "kiln_train::RolloutProvenanceV1",
  "x-kiln-semantic-constraints": [
    "prompt_token_count <= input_token_ids.length",
    "action token sequence_index values are strictly increasing and index generated tokens",
    "each action token_id equals input_token_ids[sequence_index]",
    "at least one action token is sampled",
    "forced action token IDs belong to sampling.thinking_budget.close_token_ids"
  ]
}

RolloutSamplingConfigV1Resolved sampling policy used to generate a rollout.10 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`temperature`	yes	`number`	minimum 0	Resolved sampling temperature.
`top_p`	yes	`number`	minimum 0; maximum 1	Resolved nucleus-sampling probability mass.
`top_k`	yes	`integer`	minimum 0; maximum 4294967295	Resolved maximum candidate count; zero disables top-k filtering.
`min_p`	yes	`number`	minimum 0; maximum 1	Resolved minimum probability relative to the most likely token.
`max_tokens`	yes	`integer`	minimum 1	Resolved generation-token ceiling.
`repetition_penalty`	yes	`number`	exclusive minimum 0	Resolved repetition penalty.
`presence_penalty`	yes	`number`	minimum -2; maximum 2	Resolved OpenAI-style presence penalty.
`frequency_penalty`	yes	`number`	minimum -2; maximum 2	Resolved OpenAI-style frequency penalty.
`stop`	yes	`array<string>`	maximum items 256	Resolved stop sequences.
`thinking_budget`	no	`RolloutThinkingBudgetV1`	-	Resolved thinking limit when one applied.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "RolloutSamplingConfigV1",
  "x-kiln-semantic-constraints": [
    "sum of UTF-8 stop-sequence bytes <= 16384"
  ]
}

RolloutThinkingBudgetV1Resolved thinking limit and the token sequence used to close the thinking block.3 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`max_tokens`	no	`NonNegativeInteger`	-	Maximum thinking tokens before forced closure.
`max_time_ms`	no	`NonNegativeInteger`	-	Maximum thinking time in milliseconds before forced closure.
`close_token_ids`	yes	`array<integer>`	minimum items 1	Token sequence forced when a thinking limit closes the thinking block.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "anyOf": [
    {
      "required": [
        "max_tokens"
      ]
    },
    {
      "required": [
        "max_time_ms"
      ]
    }
  ]
}

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "RolloutThinkingBudgetV1"
}

RolloutTokenizerIdentityV1Content hashes for the tokenizer vocabulary, configuration, and chat template.3 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`vocab_sha256`	yes	`Sha256`	-	Hash of tokenizer vocabulary content.
`config_sha256`	yes	`Sha256`	-	Hash of tokenizer configuration content.
`chat_template_sha256`	yes	`Sha256`	-	Hash of the chat template used to render the rollout prompt.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "RolloutTokenizerIdentityV1"
}

SamplingPresetNamed sampling profile. Known values are `qwen3-thinking-general`, `qwen3-thinking-coding`, `qwen3-non-thinking-general`, `qwen3-non-thinking-reasoning`, and `greedy`. For compatibility, the current runtime maps an unknown string to `qwen3-thinking-general` instead of rejecting it.0 fields

Type: null | string.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "string"
    }
  ]
}

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-known-values": [
    "greedy",
    "qwen3-non-thinking-general",
    "qwen3-non-thinking-reasoning",
    "qwen3-thinking-coding",
    "qwen3-thinking-general"
  ],
  "x-kiln-unknown-value-policy": "fallback_to_qwen3_thinking_general"
}

Sha256A lowercase SHA-256 digest prefixed with sha256:.0 fields

Type: string. Constraints: pattern ^sha256:[0-9a-f]{64}$.

StopInputMissing or null means no explicit stop sequence. One string and an array of strings normalize to the same internal list.0 fields

Type: null | string | array<string>.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "string"
    },
    {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  ]
}

StreamOptionsOptions that control additional events in a streaming response.1 field

Type: object.

Field	Required	Type	Constraints and default	Description
`include_usage`	no	`boolean`	default false	Emit a final empty-choices chunk containing usage before [DONE].

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "StreamOptions",
  "x-kiln-unknown-field-policy": "accepted_and_ignored"
}

StreamingTerminalMetadataMetadata attached only to the terminal finish chunk.2 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`thinking_budget`	yes	`record`	-	Resolved and terminal thinking-budget record.
`performance`	no	`ChatCompletionPerformanceMetadata`	-	Performance metadata when explicitly requested.

StreamingTokenTimingRequest-relative timestamps and blocking attribution for one streamed token.14 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`object`	yes	`any`	const "kiln.token_timing"	Kiln token-timing event discriminator.
`source`	yes	`string`	enum "batching_engine", "direct"	Producer path that owns ready and delivery timestamps.
`token_index`	yes	`integer`	minimum 0; maximum 4294967295	Zero-based generated-token index.
`token_id`	yes	`integer`	minimum 0; maximum 4294967295	Accepted model token represented by this timing event, including a special token that decodes to no visible text.
`ready_ms`	yes	`number`	minimum 0	Time when model work produced the token, relative to request start.
`producer_delivered_ms`	yes	`number`	minimum 0	Time when the generation producer handed off the token.
`handler_received_ms`	yes	`number`	minimum 0	Time when the HTTP handler received the token.
`body_enqueued_ms`	yes	`number`	minimum 0	Time when the handler enqueued the token event for the response body.
`response_delivery_ms`	yes	`number`	minimum 0	Delay from token readiness to producer handoff.
`handler_queue_ms`	yes	`number`	minimum 0	Delay from producer handoff to HTTP-handler receipt.
`queue_delay_ms`	yes	`number`	minimum 0	Compatibility aggregate equal to response_delivery_ms + handler_queue_ms.
`client_delivery_ms`	yes	`number`	minimum 0	Delay from handler receipt to response-body enqueue.
`blocking_phase`	yes	`string \| null`	enum "actor_queue", "actor_admission", "actor_prefill", "actor_decode", "actor_cycle_idle", "response_delivery", "handler_queue", "client_delivery", "sampling", "readback", "gpu_lock_wait", "graph_capture", "graph_replay", "synchronization", "resize", "trim", "adapter", "training", "unexplained", null	Phase attributed as the dominant blocking interval for this token, or null.
`blocking_phase_ms`	yes	`NullableNonNegativeNumber`	-	Blocking phase ms. A non-negative finite JSON number or null.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "StreamingTokenTiming"
}

TextCompletionChoicePrompt log probabilities and termination status for one scored prompt.4 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`index`	yes	`NonNegativeInteger`	-	Zero-based choice index; always zero for this endpoint.
`text`	yes	`string`	-	Generated text; empty in prompt-logprob scoring mode.
`finish_reason`	yes	`FinishReason`	-	Why prompt scoring ended.
`prompt_logprobs`	no	`array<null \| PromptLogprobMap>`	-	One entry per prompt token. The first is null; later maps contain the observed token plus requested top-K candidates.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "TextCompletionChoice"
}

TextCompletionRequestScore prompt-token log probabilities through the compatibility completions endpoint.7 fields

Type: object.

Field	Required	Type	Constraints and default	Description
`model`	no	`NullableString`	-	Must match the served base model when non-null.
`prompt`	yes	`string \| array<integer>`	-	Text or raw token IDs. The tokenized prompt is capped at 4096 and the served context length.
`max_tokens`	no	`null \| integer`	default 1	Must be null, 0, or 1. This endpoint scores prompt log probabilities; it does not provide general text generation.
`prompt_logprobs`	yes	`integer`	minimum 0; maximum 256	Requested top K. The runtime also caps K by vocabulary size and total returned candidates at 65536.
`n`	no	`null \| any`	default 1	Compatibility field. Missing, null, and 1 all request the single supported choice.
`stream`	no	`any`	const false; default false	Prompt-logprob scoring is non-streaming only.
`add_special_tokens`	no	`boolean`	default true	Tokenizer special-token insertion for text prompts; ignored for token-ID prompts.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-field-schema-status": "complete",
  "x-kiln-rust-type": "TextCompletionRequest",
  "x-kiln-semantic-constraints": [
    "the tokenized prompt is non-empty and has at most min(4096, served context length) tokens",
    "raw token IDs and prompt_logprobs do not exceed the served vocabulary",
    "scored positions * (prompt_logprobs + 1) <= 65536",
    "real scoring rejects an active LoRA until adapter revision identity can be pinned"
  ],
  "x-kiln-unknown-field-policy": "accepted_and_ignored"
}

TextCompletionResponsePrompt-token log probabilities, identity, and token usage for one scored prompt.7 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`id`	yes	`string`	pattern ^cmpl-	Unique completion identifier.
`object`	yes	`any`	const "text_completion"	OpenAI-compatible text-completion discriminator.
`created`	yes	`UnixSeconds`	-	Created. Whole seconds since the Unix epoch.
`model`	yes	`string`	-	Served base-model ID used for scoring.
`system_fingerprint`	yes	`NullableString`	-	Canonical content-addressed teacher identity; mock responses retain the field as null.
`choices`	yes	`array<TextCompletionChoice>`	minimum items 1; maximum items 1	The single prompt-scoring choice.
`usage`	yes	`Usage`	-	Usage. Prompt, completion, and total token counts.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-field-schema-status": "complete",
  "x-kiln-rust-type": "TextCompletionResponse"
}

ThinkingBudgetConfigurationMetadataRequest-wide resolved thinking limits and their configuration sources.5 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`configured`	yes	`boolean`	-	Whether either resolved thinking limit is finite.
`max_tokens`	no	`NonNegativeInteger`	-	Resolved thinking-token limit; omitted when unlimited.
`max_time_ms`	no	`NonNegativeInteger`	-	Resolved thinking-time limit in milliseconds; omitted when unlimited.
`tokens_source`	yes	`source`	-	Authority that supplied or removed the thinking-token limit.
`time_source`	yes	`source`	-	Authority that supplied or removed the thinking-time limit.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "ThinkingBudgetConfigurationMetadata"
}

ToolCallArrayOpaque OpenAI-shaped tool-call values. Kiln normalizes generated Qwen tool calls but preserves prior-turn values for template round trips.0 fields

Type: array<any>.

UnixSecondsWhole seconds since the Unix epoch.0 fields

Type: integer. Constraints: minimum 0.

UsagePrompt, completion, and total token counts.3 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`prompt_tokens`	yes	`NonNegativeInteger`	-	Number of prompt tokens processed.
`completion_tokens`	yes	`NonNegativeInteger`	-	Number of generated tokens.
`total_tokens`	yes	`NonNegativeInteger`	-	Prompt tokens plus completion tokens.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-rust-type": "Usage",
  "x-kiln-semantic-constraints": [
    "total_tokens = prompt_tokens + completion_tokens"
  ]
}