API Reference

Responses

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create a grounded response (streaming)

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

POST/v1/responses

Runs the grounded search pipeline (Plan → Collect → Process → Analyze) and streams results as Server-Sent Events following the OpenAI Responses API format.

ParametersExpand Collapse

body: ResponseCreateParams { input, effort, model, 2 more }

input: string | Array<UnionMember1>

User message string or array of input items.

One of the following:

string

Array<UnionMember1>

content?: string | unknown | null

One of the following:

string

unknown

role?: string

effort?: "low" | "medium" | "high" | "max"

Anthropic API effort level. Defaults to high.

One of the following:

"low"

"medium"

"high"

"max"

model?: string

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

params?: Params

Pipeline parameters. Merged with the high preset defaults.

exaCategory?: "" | "company" | "research paper" | 6 more

One of the following:

""

"company"

"research paper"

"news"

"pdf"

"github"

"tweet"

"personal site"

"financial report"

exaExcludeDomains?: Array<string>

exaExcludeText?: Array<string>

exaIncludeDomains?: Array<string>

exaIncludeText?: Array<string>

exaNumResults?: number

exaStartPublishedDate?: string

ISO date (YYYY-MM-DD)

maxSnippetsPerSource?: number

planMaxQueries?: number

stream?: boolean

Must be true — only streaming mode is supported.

ReturnsExpand Collapse

ResponseCreateResponse = ResponseCreatedEvent { response, type } | ResponseInProgressEvent { response, type } | ResponsePipelineStageEvent { pipeline_stage, type } | 7 more

One of the following:

ResponseCreatedEvent { response, type }

response: Response { id, created_at, model, 3 more }

id: string

created_at: number

model: string

object: "response"

output: Array<unknown>

status: "in_progress"

type: "response.created"

ResponseInProgressEvent { response, type }

response: Response { id, object, status }

id: string

object: "response"

status: "in_progress"

type: "response.in_progress"

ResponsePipelineStageEvent { pipeline_stage, type }

pipeline_stage: UnionMember0 { stage, status } | UnionMember1 { duration_ms, intent, queries, 2 more } | UnionMember2 { stage, status, total_queries } | 7 more

One of the following:

UnionMember0 { stage, status }

stage: "planning"

status: "in_progress"

UnionMember1 { duration_ms, intent, queries, 2 more }

duration_ms: number

intent: string

queries: Array<Query>

desired_snippets: string

Describes what snippets to extract from results of this query.

query: string

startPublishedDate?: string

Optional ISO date — only return results published after this date.

stage: "planning"

status: "done"

UnionMember2 { stage, status, total_queries }

stage: "collecting"

status: "in_progress"

total_queries: number

UnionMember3 { completed_queries, sources, stage, 2 more }

completed_queries: number

sources: Array<CollectedSourceSummary { author, favicon, image, 8 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

title: string

url: string

providers?: Array<string>

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

stage: "collecting"

status: "progress"

total_queries: number

UnionMember4 { duration_ms, sources, stage, status }

duration_ms: number

sources: Array<CollectedSourceSummary { author, favicon, image, 8 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

title: string

url: string

providers?: Array<string>

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

stage: "collecting"

status: "done"

UnionMember5 { stage, status, total_sources }

stage: "processing"

status: "in_progress"

total_sources: number

UnionMember6 { completed_sources, snippets, stage, 2 more }

completed_sources: number

snippets: Array<Snippet { source_index, text, verified, num } >

source_index: number

text: string

The relevant passage extracted from the source.

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.

stage: "processing"

status: "progress"

total_sources: number

UnionMember7 { duration_ms, snippets, stage, status }

duration_ms: number

snippets: Array<Snippet { source_index, text, verified, num } >

source_index: number

text: string

The relevant passage extracted from the source.

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.

stage: "processing"

status: "done"

UnionMember8 { stage, status }

stage: "analysis"

status: "in_progress"

UnionMember9 { duration_ms, stage, status }

duration_ms: number

stage: "analysis"

status: "done"

type: "response.pipeline_stage"

ResponseOutputItemAddedEvent { item, output_index, type }

item: Item { id, content, role, type }

id: string

content: Array<unknown>

role: "assistant"

type: "message"

output_index: number

type: "response.output_item.added"

ResponseOutputItemDoneEvent { item, output_index, type }

item: Item { id, type }

id: string

type: "message"

output_index: number

type: "response.output_item.done"

ResponseContentPartAddedEvent { content_index, item_id, part, type }

content_index: number

item_id: string

part: Part { annotations, text, type }

annotations: Array<unknown>

text: string

type: "output_text"

type: "response.content_part.added"

ResponseContentPartDoneEvent { content_index, item_id, part, type }

content_index: number

item_id: string

part: Part { annotations, text, type }

annotations: Array<Annotation>

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

cited_text?: string

text: string

type: "output_text"

type: "response.content_part.done"

ResponseOutputTextDeltaEvent { content_index, delta, item_id, type }

content_index: number

delta: string

item_id: string

type: "response.output_text.delta"

ResponseCompletedEvent { response, type }

response: Response { id, object, output, 2 more }

id: string

object: "response"

output: Array<unknown>

status: "completed"

usage?: Usage { cache_creation_input_tokens, cache_read_input_tokens, exa_cost_usd, 4 more }

cache_creation_input_tokens?: number

cache_read_input_tokens?: number

exa_cost_usd?: number

input_tokens?: number

output_tokens?: number

search_cost_usd?: number

total_cost_usd?: number

type: "response.completed"

ResponseFailedEvent { response, type }

response: Response { id, error, object, status }

id: string

error: Error { code, message, type }

code: string

message: string

type: string

object: "response"

status: "failed"

type: "response.failed"

Create a grounded response (streaming)

TypeScript

HTTP

TypeScript

import CementedAI from 'cemented.ai';

const client = new CementedAI({
  apiKey: process.env['CEMENTED_AI_API_KEY'], // This is the default and can be omitted
});

const response = await client.responses.create({ input: 'string' });

console.log(response);

200 example

{
  "response": {
    "id": "id",
    "created_at": 0,
    "model": "model",
    "object": "response",
    "output": [
      {}
    ],
    "status": "in_progress"
  },
  "type": "response.created"
}

Returns Examples

200 example

{
  "response": {
    "id": "id",
    "created_at": 0,
    "model": "model",
    "object": "response",
    "output": [
      {}
    ],
    "status": "in_progress"
  },
  "type": "response.created"
}