API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Responses

Create a grounded response

client.responses.create(ResponseCreateParams { input, effort, model, 7 more } body, RequestOptionsoptions?): ResponseCreateResponse

POST/v1/responses

ModelsExpand Collapse

CollectedSourceSummary = UnionMember0 { author, favicon, image, 14 more } | UnionMember1 { artifact_id, author, content_type, 17 more }

One of the following:

UnionMember0 { author, favicon, image, 14 more }

author: string | null

favicon: string | null

image: string | null

published_date: string | null

query_index: number

query_indices: Array<number>

result_index: number

score: number | null

source_type: "web"

Source came from web search.

title: string

url: string

domain_credibility?: DomainCredibility | null

Domain credibility assessment (1-10 score with label). Separate from LLM-assigned quality score.

label: string

score: number

minimum1

maximum10

explanation?: string | null

What this source is, why it is relevant, and why it got its quality score.

meta?: Array<UnionMember0 { kind, model, api_ms, 13 more } | UnionMember1 { kind, model, api_ms, 12 more } >

Per-source extraction attempts for admin debug view. One entry per LLM call.

One of the following:

UnionMember0 { kind, model, api_ms, 13 more }

kind: "text"

model: string

api_ms?: number

cache_read_input_tokens?: number

error?: string

explanation?: string

failed_verification_count?: number

failed_verification_samples?: Array<FailedVerificationSample>

reason: string

text: string

score?: number

input_tokens?: number

n_snippets?: number

nonempty_snippet_count?: number

output_tokens?: number

quality?: number

raw_snippet_count?: number

skipped_for_limit_count?: number

verified_snippet_count?: number

UnionMember1 { kind, model, api_ms, 12 more }

kind: "image_context"

model: string

api_ms?: number

cache_read_input_tokens?: number

error?: string

failed_verification_count?: number

failed_verification_samples?: Array<FailedVerificationSample>

reason: string

text: string

score?: number

fetch_ms?: number

fetched_content_type?: string

input_tokens?: number

markitdown_ms?: number

n_snippets?: number

output_tokens?: number

raw_image_context_count?: number

verified_image_context_count?: number

model?: string | null

Model that produced the final snippets for this source.

providers?: Array<string>

Provider names that returned this URL (admin-only).

quality?: number | null

Source quality score 0-10 (10 = best). 10 = current primary source (e.g. SEC filing, enacted statute, binding court opinion). 5-6 = secondary/pending (e.g. pending bill, law firm alert). 0 = irrelevant or unreliable (no snippets extracted).

minimum0

maximum10

UnionMember1 { artifact_id, author, content_type, 17 more }

artifact_id: string

Artifact ID for uploaded file sources.

author: string | null

content_type: string

Content type for uploaded file sources.

favicon: string | null

filename: string

Original filename for uploaded file sources.

image: string | null

published_date: string | null

query_index: number

query_indices: Array<number>

result_index: number

score: number | null

source_type: "file"

Source came from an uploaded file.

title: string

url: string

domain_credibility?: DomainCredibility | null

Domain credibility assessment (1-10 score with label). Separate from LLM-assigned quality score.

label: string

score: number

minimum1

maximum10

explanation?: string | null

What this source is, why it is relevant, and why it got its quality score.

meta?: Array<UnionMember0 { kind, model, api_ms, 13 more } | UnionMember1 { kind, model, api_ms, 12 more } >

Per-source extraction attempts for admin debug view. One entry per LLM call.

One of the following:

UnionMember0 { kind, model, api_ms, 13 more }

kind: "text"

model: string

api_ms?: number

cache_read_input_tokens?: number

error?: string

explanation?: string

failed_verification_count?: number

failed_verification_samples?: Array<FailedVerificationSample>

reason: string

text: string

score?: number

input_tokens?: number

n_snippets?: number

nonempty_snippet_count?: number

output_tokens?: number

quality?: number

raw_snippet_count?: number

skipped_for_limit_count?: number

verified_snippet_count?: number

UnionMember1 { kind, model, api_ms, 12 more }

kind: "image_context"

model: string

api_ms?: number

cache_read_input_tokens?: number

error?: string

failed_verification_count?: number

failed_verification_samples?: Array<FailedVerificationSample>

reason: string

text: string

score?: number

fetch_ms?: number

fetched_content_type?: string

input_tokens?: number

markitdown_ms?: number

n_snippets?: number

output_tokens?: number

raw_image_context_count?: number

verified_image_context_count?: number

model?: string | null

Model that produced the final snippets for this source.

providers?: Array<string>

Provider names that returned this URL (admin-only).

quality?: number | null

Source quality score 0-10 (10 = best). 10 = current primary source (e.g. SEC filing, enacted statute, binding court opinion). 5-6 = secondary/pending (e.g. pending bill, law firm alert). 0 = irrelevant or unreliable (no snippets extracted).

minimum0

maximum10

Snippet = UnionMember0 { source_index, text, type, 3 more } | UnionMember1 { end_index, num, source_index, 2 more } | UnionMember2 { caption, context, image_url, 9 more }

One of the following:

UnionMember0 { source_index, text, type, 3 more }

source_index: number

text: string

The relevant passage extracted from the source.

type: "text"

verified: boolean

Whether the snippet text was verified as a substring of the source document.

num?: number

Sequential number assigned to verified snippets (1-based). Unverified snippets have no num.

source_offset?: number | null

Character offset of the snippet within the source document. Used for ordering snippets by position.

UnionMember1 { end_index, num, source_index, 2 more }

end_index: number

End character offset into source.full_text (exclusive).

num: number

Sequential number assigned to this snippet (1-based). Always present for index snippets.

source_index: number

start_index: number

Start character offset into source.full_text.

type: "index"

UnionMember2 { caption, context, image_url, 9 more }

caption: string

The image caption or alt text copied from the source.

context: string

Nearby explanatory context copied verbatim from the source.

image_url: string

The image URL extracted from the source.

source_index: number

type: "image"

verified: boolean

Whether both the caption and context were verified against the source document.

caption_end_index?: number | null

End character offset of the verified caption in source.full_text (exclusive).

caption_start_index?: number | null

Start character offset of the verified caption in source.full_text.

content_length?: number

Image file size in bytes, if the reachability probe returned a Content-Length (or Content-Range total).

minimum0

context_end_index?: number | null

End character offset of the verified context in source.full_text (exclusive).

context_start_index?: number | null

Start character offset of the verified context in source.full_text.

num?: number

Sequential number assigned to verified snippets (1-based). Unverified snippets have no num.