## Create

**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.

### Body Parameters

- `input: string or array of object { content, role }`

  User message string or array of input items.

  - `UnionMember0 = string`

  - `UnionMember1 = array of object { content, role }`

    - `content: optional string or unknown`

      - `UnionMember0 = string`

      - `UnionMember1 = unknown`

    - `role: optional string`

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

  Anthropic API effort level. Defaults to high.

  - `"low"`

  - `"medium"`

  - `"high"`

  - `"max"`

- `model: optional string`

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

- `params: optional object { exaCategory, exaExcludeDomains, exaExcludeText, 6 more }`

  Pipeline parameters. Merged with the high preset defaults.

  - `exaCategory: optional "" or "company" or "research paper" or 6 more`

    - `""`

    - `"company"`

    - `"research paper"`

    - `"news"`

    - `"pdf"`

    - `"github"`

    - `"tweet"`

    - `"personal site"`

    - `"financial report"`

  - `exaExcludeDomains: optional array of string`

  - `exaExcludeText: optional array of string`

  - `exaIncludeDomains: optional array of string`

  - `exaIncludeText: optional array of string`

  - `exaNumResults: optional number`

  - `exaStartPublishedDate: optional string`

    ISO date (YYYY-MM-DD)

  - `maxSnippetsPerSource: optional number`

  - `planMaxQueries: optional number`

- `stream: optional boolean`

  Must be true — only streaming mode is supported.

### Returns

- `ResponseCreated = object { response, type }`

  - `response: object { id, created_at, model, 3 more }`

    - `id: string`

    - `created_at: number`

    - `model: string`

    - `object: "response"`

      - `"response"`

    - `output: array of unknown`

    - `status: "in_progress"`

      - `"in_progress"`

  - `type: "response.created"`

    - `"response.created"`

- `ResponseInProgress = object { response, type }`

  - `response: object { id, object, status }`

    - `id: string`

    - `object: "response"`

      - `"response"`

    - `status: "in_progress"`

      - `"in_progress"`

  - `type: "response.in_progress"`

    - `"response.in_progress"`

- `ResponsePipelineStage = object { pipeline_stage, type }`

  - `pipeline_stage: object { stage, status }  or object { duration_ms, intent, queries, 2 more }  or object { stage, status, total_queries }  or 7 more`

    - `UnionMember0 = object { stage, status }`

      - `stage: "planning"`

        - `"planning"`

      - `status: "in_progress"`

        - `"in_progress"`

    - `UnionMember1 = object { duration_ms, intent, queries, 2 more }`

      - `duration_ms: number`

      - `intent: string`

      - `queries: array of object { desired_snippets, query, startPublishedDate }`

        - `desired_snippets: string`

          Describes what snippets to extract from results of this query.

        - `query: string`

        - `startPublishedDate: optional string`

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

      - `stage: "planning"`

        - `"planning"`

      - `status: "done"`

        - `"done"`

    - `UnionMember2 = object { stage, status, total_queries }`

      - `stage: "collecting"`

        - `"collecting"`

      - `status: "in_progress"`

        - `"in_progress"`

      - `total_queries: number`

    - `UnionMember3 = object { completed_queries, sources, stage, 2 more }`

      - `completed_queries: number`

      - `sources: array of CollectedSourceSummary`

        - `author: string`

        - `favicon: string`

        - `image: string`

        - `published_date: string`

        - `query_index: number`

        - `query_indices: array of number`

        - `result_index: number`

        - `score: number`

        - `title: string`

        - `url: string`

        - `providers: optional array of string`

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

      - `stage: "collecting"`

        - `"collecting"`

      - `status: "progress"`

        - `"progress"`

      - `total_queries: number`

    - `UnionMember4 = object { duration_ms, sources, stage, status }`

      - `duration_ms: number`

      - `sources: array of CollectedSourceSummary`

        - `author: string`

        - `favicon: string`

        - `image: string`

        - `published_date: string`

        - `query_index: number`

        - `query_indices: array of number`

        - `result_index: number`

        - `score: number`

        - `title: string`

        - `url: string`

        - `providers: optional array of string`

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

      - `stage: "collecting"`

        - `"collecting"`

      - `status: "done"`

        - `"done"`

    - `UnionMember5 = object { stage, status, total_sources }`

      - `stage: "processing"`

        - `"processing"`

      - `status: "in_progress"`

        - `"in_progress"`

      - `total_sources: number`

    - `UnionMember6 = object { completed_sources, snippets, stage, 2 more }`

      - `completed_sources: number`

      - `snippets: array of 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: optional number`

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

      - `stage: "processing"`

        - `"processing"`

      - `status: "progress"`

        - `"progress"`

      - `total_sources: number`

    - `UnionMember7 = object { duration_ms, snippets, stage, status }`

      - `duration_ms: number`

      - `snippets: array of 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: optional number`

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

      - `stage: "processing"`

        - `"processing"`

      - `status: "done"`

        - `"done"`

    - `UnionMember8 = object { stage, status }`

      - `stage: "analysis"`

        - `"analysis"`

      - `status: "in_progress"`

        - `"in_progress"`

    - `UnionMember9 = object { duration_ms, stage, status }`

      - `duration_ms: number`

      - `stage: "analysis"`

        - `"analysis"`

      - `status: "done"`

        - `"done"`

  - `type: "response.pipeline_stage"`

    - `"response.pipeline_stage"`

- `ResponseOutputItemAdded = object { item, output_index, type }`

  - `item: object { id, content, role, type }`

    - `id: string`

    - `content: array of unknown`

    - `role: "assistant"`

      - `"assistant"`

    - `type: "message"`

      - `"message"`

  - `output_index: number`

  - `type: "response.output_item.added"`

    - `"response.output_item.added"`

- `ResponseOutputItemDone = object { item, output_index, type }`

  - `item: object { id, type }`

    - `id: string`

    - `type: "message"`

      - `"message"`

  - `output_index: number`

  - `type: "response.output_item.done"`

    - `"response.output_item.done"`

- `ResponseContentPartAdded = object { content_index, item_id, part, type }`

  - `content_index: number`

  - `item_id: string`

  - `part: object { annotations, text, type }`

    - `annotations: array of unknown`

    - `text: string`

    - `type: "output_text"`

      - `"output_text"`

  - `type: "response.content_part.added"`

    - `"response.content_part.added"`

- `ResponseContentPartDone = object { content_index, item_id, part, type }`

  - `content_index: number`

  - `item_id: string`

  - `part: object { annotations, text, type }`

    - `annotations: array of object { end_index, start_index, title, 3 more }`

      - `end_index: number`

      - `start_index: number`

      - `title: string`

      - `type: "url_citation"`

        - `"url_citation"`

      - `url: string`

      - `cited_text: optional string`

    - `text: string`

    - `type: "output_text"`

      - `"output_text"`

  - `type: "response.content_part.done"`

    - `"response.content_part.done"`

- `ResponseOutputTextDelta = object { content_index, delta, item_id, type }`

  - `content_index: number`

  - `delta: string`

  - `item_id: string`

  - `type: "response.output_text.delta"`

    - `"response.output_text.delta"`

- `ResponseCompleted = object { response, type }`

  - `response: object { id, object, output, 2 more }`

    - `id: string`

    - `object: "response"`

      - `"response"`

    - `output: array of unknown`

    - `status: "completed"`

      - `"completed"`

    - `usage: optional object { cache_creation_input_tokens, cache_read_input_tokens, exa_cost_usd, 4 more }`

      - `cache_creation_input_tokens: optional number`

      - `cache_read_input_tokens: optional number`

      - `exa_cost_usd: optional number`

      - `input_tokens: optional number`

      - `output_tokens: optional number`

      - `search_cost_usd: optional number`

      - `total_cost_usd: optional number`

  - `type: "response.completed"`

    - `"response.completed"`

- `ResponseFailed = object { response, type }`

  - `response: object { id, error, object, status }`

    - `id: string`

    - `error: object { code, message, type }`

      - `code: string`

      - `message: string`

      - `type: string`

    - `object: "response"`

      - `"response"`

    - `status: "failed"`

      - `"failed"`

  - `type: "response.failed"`

    - `"response.failed"`

### Example

```http
curl https://api.example.com/v1/responses \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CEMENTED_AI_API_KEY" \
    -d '{
          "input": "string"
        }'
```