# Responses ## Create `client.responses.create(ResponseCreateParamsbody, 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. ### Parameters - `body: ResponseCreateParams` - `input: string | Array` User message string or array of input items. - `string` - `Array` - `content?: string | unknown | null` - `string` - `unknown` - `role?: string` - `effort?: "low" | "medium" | "high" | "max"` Anthropic API effort level. Defaults to high. - `"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` - `""` - `"company"` - `"research paper"` - `"news"` - `"pdf"` - `"github"` - `"tweet"` - `"personal site"` - `"financial report"` - `exaExcludeDomains?: Array` - `exaExcludeText?: Array` - `exaIncludeDomains?: Array` - `exaIncludeText?: Array` - `exaNumResults?: number` - `exaStartPublishedDate?: string` ISO date (YYYY-MM-DD) - `maxSnippetsPerSource?: number` - `planMaxQueries?: number` - `stream?: boolean` Must be true — only streaming mode is supported. ### Returns - `ResponseCreateResponse = ResponseCreatedEvent | ResponseInProgressEvent | ResponsePipelineStageEvent | 7 more` - `ResponseCreatedEvent` - `response: Response` - `id: string` - `created_at: number` - `model: string` - `object: "response"` - `"response"` - `output: Array` - `status: "in_progress"` - `"in_progress"` - `type: "response.created"` - `"response.created"` - `ResponseInProgressEvent` - `response: Response` - `id: string` - `object: "response"` - `"response"` - `status: "in_progress"` - `"in_progress"` - `type: "response.in_progress"` - `"response.in_progress"` - `ResponsePipelineStageEvent` - `pipeline_stage: UnionMember0 | UnionMember1 | UnionMember2 | 7 more` - `UnionMember0` - `stage: "planning"` - `"planning"` - `status: "in_progress"` - `"in_progress"` - `UnionMember1` - `duration_ms: number` - `intent: string` - `queries: Array` - `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"` - `"planning"` - `status: "done"` - `"done"` - `UnionMember2` - `stage: "collecting"` - `"collecting"` - `status: "in_progress"` - `"in_progress"` - `total_queries: number` - `UnionMember3` - `completed_queries: number` - `sources: Array` - `author: string | null` - `favicon: string | null` - `image: string | null` - `published_date: string | null` - `query_index: number` - `query_indices: Array` - `result_index: number` - `score: number | null` - `title: string` - `url: string` - `providers?: Array` Provider names that returned this URL (admin-only). - `stage: "collecting"` - `"collecting"` - `status: "progress"` - `"progress"` - `total_queries: number` - `UnionMember4` - `duration_ms: number` - `sources: Array` - `author: string | null` - `favicon: string | null` - `image: string | null` - `published_date: string | null` - `query_index: number` - `query_indices: Array` - `result_index: number` - `score: number | null` - `title: string` - `url: string` - `providers?: Array` Provider names that returned this URL (admin-only). - `stage: "collecting"` - `"collecting"` - `status: "done"` - `"done"` - `UnionMember5` - `stage: "processing"` - `"processing"` - `status: "in_progress"` - `"in_progress"` - `total_sources: number` - `UnionMember6` - `completed_sources: number` - `snippets: Array` - `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"` - `"processing"` - `status: "progress"` - `"progress"` - `total_sources: number` - `UnionMember7` - `duration_ms: number` - `snippets: Array` - `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"` - `"processing"` - `status: "done"` - `"done"` - `UnionMember8` - `stage: "analysis"` - `"analysis"` - `status: "in_progress"` - `"in_progress"` - `UnionMember9` - `duration_ms: number` - `stage: "analysis"` - `"analysis"` - `status: "done"` - `"done"` - `type: "response.pipeline_stage"` - `"response.pipeline_stage"` - `ResponseOutputItemAddedEvent` - `item: Item` - `id: string` - `content: Array` - `role: "assistant"` - `"assistant"` - `type: "message"` - `"message"` - `output_index: number` - `type: "response.output_item.added"` - `"response.output_item.added"` - `ResponseOutputItemDoneEvent` - `item: Item` - `id: string` - `type: "message"` - `"message"` - `output_index: number` - `type: "response.output_item.done"` - `"response.output_item.done"` - `ResponseContentPartAddedEvent` - `content_index: number` - `item_id: string` - `part: Part` - `annotations: Array` - `text: string` - `type: "output_text"` - `"output_text"` - `type: "response.content_part.added"` - `"response.content_part.added"` - `ResponseContentPartDoneEvent` - `content_index: number` - `item_id: string` - `part: Part` - `annotations: Array` - `end_index: number` - `start_index: number` - `title: string` - `type: "url_citation"` - `"url_citation"` - `url: string` - `cited_text?: string` - `text: string` - `type: "output_text"` - `"output_text"` - `type: "response.content_part.done"` - `"response.content_part.done"` - `ResponseOutputTextDeltaEvent` - `content_index: number` - `delta: string` - `item_id: string` - `type: "response.output_text.delta"` - `"response.output_text.delta"` - `ResponseCompletedEvent` - `response: Response` - `id: string` - `object: "response"` - `"response"` - `output: Array` - `status: "completed"` - `"completed"` - `usage?: Usage` - `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"` - `"response.completed"` - `ResponseFailedEvent` - `response: Response` - `id: string` - `error: Error` - `code: string` - `message: string` - `type: string` - `object: "response"` - `"response"` - `status: "failed"` - `"failed"` - `type: "response.failed"` - `"response.failed"` ### Example ```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); ``` ## Domain Types ### Collected Source Summary - `CollectedSourceSummary` - `author: string | null` - `favicon: string | null` - `image: string | null` - `published_date: string | null` - `query_index: number` - `query_indices: Array` - `result_index: number` - `score: number | null` - `title: string` - `url: string` - `providers?: Array` Provider names that returned this URL (admin-only). ### Snippet - `Snippet` - `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.