API Reference

Responses

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create a grounded response

POST/v1/responses

Runs the grounded search pipeline (Plan → Collect → Process → Analyze) and returns a cited answer in the OpenAI Responses API shape.

Non-streaming (default). Omit stream (or pass stream: false) to receive a single JSON body equal to the response field of the terminal response.completed event. This matches OpenAI's spec.

Streaming. Pass stream: true to receive a Server-Sent Events stream of OpenAI Responses events: response.created → response.in_progress → response.output_item.added → response.output_text.delta* → response.output_item.done → response.completed. The official OpenAI SDKs consume this stream natively.

Drop-in mode. Pass vendor_events: false (recommended for SDK consumers) to suppress non-OpenAI events: response.pipeline_stage, response.source_texts, and the web_search_call output item. Leave it true if you want to surface pipeline progress (planning, collection, processing) in your UI.

Citations. Every output_text content part carries a url_citation annotation for each inline [N] marker — see the UrlCitationAnnotation schema and the API overview above for code that expands them into footnotes or tooltips.

Follow-up turns. Pass request_id from a prior response to continue the same conversation; input is appended to the existing history.

Body ParametersJSONExpand Collapse

input: string or array of object { content, role, snippets, sources }

User message string or array of input items.

One of the following:

UnionMember0 = string

UnionMember1 = array of object { content, role, snippets, sources }

content: optional string or unknown

One of the following:

UnionMember0 = string

UnionMember1 = unknown

role: optional string

snippets: optional array of Snippet

One of the following:

UnionMember0 = object { 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: optional number

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

source_offset: optional number

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

UnionMember1 = object { 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 = object { 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: optional number

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

caption_start_index: optional number

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

content_length: optional number

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

minimum0

context_end_index: optional number

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

context_start_index: optional number

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

num: optional number

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

sources: optional array of CollectedSourceSummary

One of the following:

UnionMember0 = object { author, favicon, image, 14 more }

author: string

favicon: string

image: string

published_date: string

query_index: number

query_indices: array of number

result_index: number

score: number

source_type: "web"

Source came from web search.

title: string

url: string

domain_credibility: optional object { label, score }

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

label: string

score: number

minimum1

maximum10

explanation: optional string

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

meta: optional array of object { kind, model, api_ms, 13 more } or object { kind, model, api_ms, 12 more }

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

One of the following:

UnionMember0 = object { kind, model, api_ms, 13 more }

kind: "text"

model: string

api_ms: optional number

cache_read_input_tokens: optional number

error: optional string

explanation: optional string

failed_verification_count: optional number

failed_verification_samples: optional array of object { reason, text, score }

reason: string

text: string

score: optional number

input_tokens: optional number

n_snippets: optional number

nonempty_snippet_count: optional number

output_tokens: optional number

quality: optional number

raw_snippet_count: optional number

skipped_for_limit_count: optional number

verified_snippet_count: optional number

UnionMember1 = object { kind, model, api_ms, 12 more }

kind: "image_context"

model: string

api_ms: optional number

cache_read_input_tokens: optional number

error: optional string

failed_verification_count: optional number

failed_verification_samples: optional array of object { reason, text, score }

reason: string

text: string

score: optional number

fetch_ms: optional number

fetched_content_type: optional string

input_tokens: optional number

markitdown_ms: optional number

n_snippets: optional number

output_tokens: optional number

raw_image_context_count: optional number

verified_image_context_count: optional number

model: optional string

Model that produced the final snippets for this source.

providers: optional array of string

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

quality: optional number

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 = object { artifact_id, author, content_type, 17 more }

artifact_id: string

Artifact ID for uploaded file sources.

author: string

content_type: string

Content type for uploaded file sources.

favicon: string

filename: string

Original filename for uploaded file sources.

image: string

published_date: string

query_index: number

query_indices: array of number

result_index: number

score: number

source_type: "file"

Source came from an uploaded file.

title: string

url: string

domain_credibility: optional object { label, score }

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

label: string

score: number

minimum1

maximum10

explanation: optional string

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

meta: optional array of object { kind, model, api_ms, 13 more } or object { kind, model, api_ms, 12 more }

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

One of the following:

UnionMember0 = object { kind, model, api_ms, 13 more }

kind: "text"

model: string

api_ms: optional number

cache_read_input_tokens: optional number

error: optional string

explanation: optional string

failed_verification_count: optional number

failed_verification_samples: optional array of object { reason, text, score }

reason: string

text: string

score: optional number

input_tokens: optional number

n_snippets: optional number

nonempty_snippet_count: optional number

output_tokens: optional number

quality: optional number

raw_snippet_count: optional number

skipped_for_limit_count: optional number

verified_snippet_count: optional number

UnionMember1 = object { kind, model, api_ms, 12 more }

kind: "image_context"

model: string

api_ms: optional number

cache_read_input_tokens: optional number

error: optional string

failed_verification_count: optional number

failed_verification_samples: optional array of object { reason, text, score }

reason: string

text: string

score: optional number

fetch_ms: optional number

fetched_content_type: optional string

input_tokens: optional number

markitdown_ms: optional number

n_snippets: optional number

output_tokens: optional number

raw_image_context_count: optional number

verified_image_context_count: optional number

model: optional string

Model that produced the final snippets for this source.

providers: optional array of string

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

quality: optional number

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

effort: optional "low" or "medium" or "high" or "max"

Anthropic API effort level. Defaults to high.

One of the following:

"low"

"medium"

"high"

"max"

model: optional string

Model ID, e.g. "grounded-sonnet" or "grounded-opus".

params: optional object { analysisMaxWords, analysisTimeoutMs, category, 13 more }

Pipeline parameters. Merged with the selected preset defaults, or deep defaults when preset is custom or omitted.

analysisMaxWords: optional number

analysisTimeoutMs: optional number

category: optional string

effort: optional "low" or "medium" or "high" or "max"

One of the following:

"low"

"medium"

"high"

"max"

excludeDomains: optional array of string

excludeText: optional array of string

imageContextMaxSources: optional number

includeDomains: optional array of string

includeText: optional array of string

maxSnippetsPerFile: optional number

maxSnippetsPerWebSource: optional number

numResults: optional number

perSourceExtractTimeoutMs: optional number

planMaxQueries: optional number

planTimeoutMs: optional number

startPublishedDate: optional string

ISO date (YYYY-MM-DD)

preset: optional "xfast" or "fast" or "deep" or 3 more

Preset name. Use "custom" when request params do not exactly match a preset.

One of the following:

"xfast"

"fast"

"deep"

"max"

"auto"

"custom"

project_id: optional string

Project ID for a new request. Ignored for follow-up turns.

formatuuid

request_id: optional string

Request ID for follow-up turns. Reuses the same request instead of creating a new one.

formatuuid

sources: optional object { file_ids, web_policy }

Uploaded-file source options.

file_ids: optional array of string

Uploaded grounded file IDs to use as sources.

web_policy: optional "off" or "web_plus_files"

When files are attached, either use only files or augment them with web search.

One of the following:

"off"

"web_plus_files"

stream: optional boolean

When true, the response is delivered as a Server-Sent Events stream. When false (default, matching OpenAI's spec), the bridge buffers events server-side and returns the terminal response.completed payload as JSON.

vendor_events: optional boolean

When false, omit non-OpenAI vendor events (response.pipeline_stage, response.source_texts) and the web_search_call output item so the SSE stream parses cleanly with the official OpenAI SDK.

Create a grounded response

HTTP

HTTP

TypeScript

curl https://www.cemented.ai/v1/responses \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CEMENTED_AI_API_KEY" \
    -d '{
          "input": "What did NVIDIA report in its latest 10-Q?"
        }'

200 example

{}

Returns Examples

200 example

{}