docs: /v1/responses validation matches the public API: top_logprobs without include accepted, unknown params refused

[github-actions]

What this PR does

Which request shapes does POST /v1/responses accept or refuse on current main — does top_logprobs still require the logprobs include entry, is an unknown top-level parameter still ignored, and what limits now apply to max_output_tokens, metadata, and input message roles?

Why we need it

Source change: smg-project/smg@9ccaa20

Commit 2 (#3063, 9ccaa20e, 2026-10-10) aligned POST /v1/responses request validation with the public API's contract; its supplied diff was read in full and every claim re-verified on the current default-branch snapshot (source_sha 02836eed, one commit later). crates/protocols/src/responses.rs:3063 — ResponsesRequest now carries #[serde(deny_unknown_fields)], doc comment :3059-3062: unknown top-level parameters are rejected as the public API rejects them (test unknown_top_level_parameter_is_rejected_at_the_body_parser in crates/protocols/tests/responses.rs; the rejection is the body parser's 400 json_parse_error envelope). background is now a declared, accepted parameter (:3074) — 'the gateway still generates in the foreground'. The top_logprobs-requires-include cross-check was deleted (comment :3587-3589: accepted as the public API accepts it, the logprobs are simply not attached; tests test_validate_top_logprobs_does_not_require_include in model_gateway/tests/spec/responses.rs and top_logprobs_without_include_is_accepted). max_output_tokens minimum is now 16 (MIN_MAX_OUTPUT_TOKENS, responses.rs:3696, validate_max_output_tokens; was validate range(min=1)). metadata is limited to 16 pairs, 64-character keys, 512-character string values (validate_metadata). Input message roles are restricted to assistant/system/developer/user via INPUT_MESSAGE_ROLES + validate_input_message_role, applied in validate_input_item to both Message and SimpleInputMessage items (e2e e2e_test/responses/test_validation.py::test_message_with_invalid_role_rejected_400, flipped by this commit from a documented known-gap to a required 400). validate_response_tools now refuses a function tool whose parameters is not a JSON object (invalid_type on tools[idx].parameters) and the local_shell tool (tool_not_supported). New vendor-scoped rules: is_openai_vendor_model (crates/protocols/src/profile/mod.rs — gpt-/chatgpt-/codex-*/o1|o3|o4 series/computer-use-preview or an openai route segment, excluding gpt-oss) gates validate_openai_structured_output_rules: for OpenAI's own hosted model ids a strict function schema or strict json_schema text format must pin additionalProperties:false on every object node (strict_schema_missing_additional_properties, crates/protocols/src/common.rs), and a json_object text format needs the word 'json' in instructions or input text; a self-hosted model passes those shapes through to the engine, whose grammar compiler decides. The same commit validates the include query of GET /v1/conversations/{id}/items/{item} against the 8 includable fields (parse_item_include_query, model_gateway/src/endpoints/conversations/handlers.rs; wired in server.rs v1_conversations_get_item) — same contract alignment on this same page's Get Conversation Item section, a one-sentence addition at most. Stale docs, all on src/lib/content/reference/api/responses.md, re-read tonight: :90 'requires message.output_text.logprobs in include' — false on main; :75 max_output_tokens '(at least 1)' — false (minimum 16); :91 metadata row states no limits; :94-95 'a background field is ignored, and every response is returned synchronously or streamed' — stale: background is declared and accepted (foreground-only stays true, as does the Cancel section :650), while every OTHER unknown top-level parameter is now rejected rather than ignored; the Input Formats section states no role rule; Tool Configuration (:176-260) lacks the parameters-must-be-an-object rule and the local_shell refusal (the Conversations item-type list at :973-978, where local_shell_call items are stored with warnings, is a different endpoint and stays as is); Text Format (:288-311) lacks the OpenAI-vendor-model-only strict/json_object rules — the edit must keep the page's example (strict:true without additionalProperties) valid for self-hosted models and must not claim the pin applies to them. One independent concern: one commit realigned the one request-validation contract of POST /v1/responses, corrected on the one page that states that contract; the same-day item_reference input resolution (#3065) and Response-object field completion (#3055) are separate concerns on this same file, deferred in remaining_work, not bundled. Version framing: the commit (2026-10-10) postdates the v1.12.0 bump (commit 159, #2888, 2026-10-08), so present as current-main behavior newer than v1.12.0, keeping the old rules (include required, minimum 1, unknown parameters ignored, roles unvalidated) as the historical caveat in the style the page already uses (:73, :171-174). Dedup: no open or closed PR mentions #3063, top_logprobs, deny_unknown_fields, or max_output_tokens (the newest PR #140 predates this commit; merged #102 covered #2723 tool-result-only continuations, already on the page at :147-174; closed-unmerged #121 covered a Responses stream-failure metric; neither is recreated). No open PR touches responses.md. Scope exclusion: openai.md:102's Chat Completions top_logprobs row ('requires logprobs: true') is a different endpoint's unchanged contract, and openai.md is held by open PR #133 — not touched. Edit is well under 1000 lines.

Scope: responses-api / request-validation-public-api-alignment. Other concerns are deferred.

How to test

• Passed the documentation path and size guard (under 1000 added plus deleted lines; no file-count limit).
• Passed an independent accuracy and single-concern review.
• Passed git diff --check and pnpm check and the production pnpm build.

Checklist

• Tests added/updated (if applicable)
• Docs updated (if applicable)
• Commit includes a DCO sign-off

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: b01147e2-b3c1-428a-b7be-322a32cb3561

---

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Documentation maintenance: needs-human. Unsuccessful content rounds: 3/3. Operational attempts: 0/3.

Head: b51982cf9dd3dc1c401b4f14a6b10381a46a97ba; reviewed main: e17c545940df0ab77f19d09285b49aa9e4773d7c.
Reviewed SMG source: a82ce28232df9b15a1fc858f54f85678d4b56f21.

All edits serve the single 9ccaa20e validation-alignment concern and nearly every claim verified against the checkout at code_sha: deny_unknown_fields on ResponsesRequest (responses.rs:3055) with the 400 json_parse_error envelope minted by ValidatedJson (validated.rs:276-282); the declared-parameter enumeration matches the struct's full field set exactly; max_output_tokens>=16 (MIN_MAX_OUTPUT_TOKENS, responses.rs:3688), metadata 16/64/512, top_logprobs 0-20 with the include cross-check removed, roles validated on both Message and SimpleInputMessage (responses.rs:3799-3808), local_shell tool_not_supported, is_openai_vendor_model gating with self-hosted passthrough keeping the page's example valid, and the Get Conversation Item include query (8 includable values, include[] accepted, invalid_value, ignored for output — handlers.rs:485-539). The rewritten conversation-errors paragraph is accurate: handlers emit the gateway envelope with generic codes invalid_request/not_found/internal_error (handlers.rs:67-77) plus exactly the two structured codes named, and the edit was forced by the concern (the paragraph had to gain the invalid_value exception; the old plain-string claim was false on current source). Version framing is evidenced: v1.12.0 is the newest tag in packed-refs, the snapshot version is 1.12.0, and the supplied commit diff's minus-lines show the prior rules. One repair is required before publishing: the new Tool Configuration sentence "any other JSON type is rejected with 400" is false for null — deserialize_parameters (crates/protocols/src/common.rs:646-653) normalizes an explicit "parameters": null to the empty schema and the request is accepted, same as omitting the field; only non-null, non-object values hit the invalid_type rejection. Qualify that sentence (e.g. "null or an omitted parameters means an empty schema; any other non-object JSON value is rejected with 400"). Minor non-blocking notes: the openai/ route-segment sentence could state that the gpt-oss exclusion also applies behind openai/ (openai/gpt-oss-120b is not gated), and the unedited Error Responses section retains claims stale against current source (reason-phrase type, code 400 for validation failures — current code uses invalid_request_error vocabulary and rule-derived codes via public_code), which stems from a different source change and should be a separate deferred concern. openai.md (held by open PR #133) correctly untouched; no other page contradicts; PR is ~120 changed lines on the single canonical page; no threads exist to address.
Documentation type check or production build did not pass.

Workflow evidence

Human review threads and CODEOWNER approval remain under repository policy.