`verified.create`

The hero endpoint: grounded generation with verbatim citations and ungrounded claims removed.

SDK: mx.verified.create(params)
HTTP: POST https://api.maxmodel.com/v1/verified
Auth: Authorization: Bearer <MAXMODEL_KEY>

Parameters

Field	Type	Default	Notes
`model`	`string`	—	Any model your gateway key can call (e.g. `gpt-5.5-pro`).
`messages`	`{ role, content }[]`	—	`role` is `system` \| `user` \| `assistant`.
`sources`	`{ id, text }[]`	—	Your own chunks. `id` is yours and is echoed back in citations. MaxModel does not retrieve in v1.
`mode`	`'strict' \| 'lenient'`	`'strict'`	How quotes are matched. See How verification works.
`allowUngrounded`	`boolean`	`false`	If `true` and a question can’t be grounded, return a flagged plain answer instead of erroring.
`temperature`	`number`	—	Passed through to the gateway.
`maxTokens`	`number`	—	Passed through to the gateway.

The total size of sources text has a budget (~100k chars). Over-budget requests return 400 sources_too_large.

Request (HTTP)

{
  "model": "gpt-5.5-pro",
  "messages": [{ "role": "user", "content": "What is our refund policy?" }],
  "sources": [
    { "id": "refunds.md", "text": "Full refunds within 30 days. No refunds after 30 days." },
    { "id": "pricing.md", "text": "Pro is $29/month, billed annually." }
  ],
  "mode": "strict",
  "allow_ungrounded": false
}

Over HTTP the fields are snake_case (allow_ungrounded, max_tokens). The TypeScript SDK uses camelCase (allowUngrounded, maxTokens) and converts for you.

Response

{
  "id": "vfd_abc123",
  "model": "gpt-5.5-pro",
  "text": "Full refunds are available within 30 days [refunds.md]. After 30 days, no refunds [refunds.md].",
  "citations": [
    {
      "claim": "Full refunds are available within 30 days",
      "quote": "Full refunds within 30 days",
      "source": "refunds.md",
      "range": [0, 27]
    }
  ],
  "unsupported": [
    { "claim": "We also offer a 14-day free trial", "reason": "quote_not_found" }
  ],
  "grounded": true,
  "usage": { "prompt_tokens": 812, "completion_tokens": 143, "total_tokens": 955, "model_calls": 1 }
}

Response fields

Field	Type	Notes
`text`	`string`	The grounded answer, with inline `[sourceId]` markers.
`citations[]`	`Citation`	One per grounded claim.
`citations[].claim`	`string`	The grounded statement.
`citations[].quote`	`string`	The verbatim span copied from the source.
`citations[].source`	`string`	The `Source.id` it came from.
`citations[].range`	`[number, number]`	Char offsets `[start, end)` into that source’s text — usable for highlighting.
`unsupported[]`	`Unsupported`	Claims that could not be grounded — caught before your users see them.
`unsupported[].reason`	`'quote_not_found' \| 'unknown_source'`	Why it was dropped.
`grounded`	`boolean`	`false` only when `allowUngrounded=true` and we fell back to a plain answer.
`usage.modelCalls`	`number`	A verified call routes ≥ 1 model call through the gateway.

In the SDK, usage is camelCase: promptTokens, completionTokens, totalTokens, modelCalls.

Streaming

/v1/verified is non-streaming in v1 — verification needs the complete claim set before it can return a trustworthy answer. Use chat.completions.create if you need token streaming without verification. Streaming verified output is a later item.

TypeScript types

interface VerifiedParams {
  model: string
  messages: { role: 'system' | 'user' | 'assistant'; content: string }[]
  sources: { id: string; text: string }[]
  mode?: 'strict' | 'lenient'
  allowUngrounded?: boolean
  temperature?: number
  maxTokens?: number
}
 
interface VerifiedResult {
  id: string
  model: string
  text: string
  citations: { claim: string; quote: string; source: string; range: [number, number] }[]
  unsupported: { claim: string; reason: 'quote_not_found' | 'unknown_source' }[]
  grounded: boolean
  usage: { promptTokens: number; completionTokens: number; totalTokens: number; modelCalls: number }
}

Quickstart How verification works