Create a grounded response

POST

/v1/responses

const url = 'https://www.cemented.ai/v1/responses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"model":"sonnet","input":"What did NVIDIA report in its latest 10-Q?","vendor_events":false}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://www.cemented.ai/v1/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model": "sonnet", "input": "What did NVIDIA report in its latest 10-Q?", "vendor_events": false }'

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. Report-mode output_text carries a url_citation annotation for each inline [N] marker. Structured output uses the normal Responses output-text content for clean serialized JSON; its field provenance remains on the persisted run for Cemented’s report UI. See the UrlCitationAnnotation schema.

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

Agents. Pass agent_id to run the turn as one of your agents (list them at GET /v1/agents; the web client resolves @handle mentions to this id client-side). A new request is placed in the agent’s project (or personal scope). If the request is later moved, a follow-up cannot invoke that agent unless both are in the same scope. Access is re-checked server-side. A prompt agent’s directions are appended to the system prompt; a code agent runs its committed implementation. Code agents may return saved artifacts alongside their structured result. Mentions in input text are not parsed server-side: an @handle without agent_id runs as a plain grounded turn. Returns 404 agent_not_found when the id doesn’t resolve to an agent you can access.

Authorizations

BearerAuth
ApiKeyHeader

Request Body^required

application/json

object

model

Model ID, e.g. “sonnet” or “opus”.

string

input

required

Any of:

string
Array<object>

string

stream

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.

boolean

params

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

object

planMaxQueries

integer

planTimeoutMs

integer

numResults

integer

maxSnippetsPerWebSource

integer

maxSnippetsPerFile

integer

analysisMaxWords

integer

analysisTimeoutMs

integer

perSourceExtractTimeoutMs

integer

imageContextMaxSources

integer

effort

string

Allowed values: low medium high max

category

string

startPublishedDate

ISO date (YYYY-MM-DD)

string

includeDomains

Array<string>

excludeDomains

Array<string>

includeText

Array<string>

excludeText

Array<string>

effort

string

Allowed values: low medium high max

preset

string

Allowed values: xfast fast deep max auto custom

sources

Uploaded-file source options.

object

file_ids

Uploaded grounded file IDs to use as sources.

Array<string>

web_policy

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

string

Allowed values: off web_plus_files

text

OpenAI-compatible text response configuration. Set text.format.type to json_schema to validate the clean structured output against the supplied schema.

object

format

One of:

object
object

object

type

required

string

Allowed values: text

object

type

required

string

Allowed values: json_schema

name

required

string

>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/

description

string

schema

required

Closed root-object JSON Schema. Supports required closed objects, homogeneous arrays, scalar types and constraints, common string formats, nullable anyOf, and acyclic local $defs/definitions references.

object

key

additional properties

strict

boolean | null

project_id

Project ID for a new request. Ignored for follow-up turns and overridden by the selected agent’s project when agent_id is present.

string format: uuid

request_id

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

string format: uuid

agent_id

Agent to run the turn as — an id from GET /v1/agents (the web client resolves @handle mentions to this; API callers pass it directly). A new request adopts the agent’s project or personal scope; a follow-up returns 409 agent_project_mismatch if the request was moved elsewhere. Access is re-checked server-side. A prompt agent’s directions are appended to the system prompt; a code agent runs its committed implementation. Returns 404 agent_not_found when the id doesn’t resolve to an agent you can access.

string format: uuid

use_perplexity

Admin-only: also query Perplexity alongside Exa for web search. Ignored (treated as false) for non-admin callers and when PERPLEXITY_API_KEY is unset. Defaults to false.

boolean

vendor_events

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.

boolean

default: true

Examples

Drop-in OpenAI usage (vendor_events off)

{
  "model": "sonnet",
  "input": "What did NVIDIA report in its latest 10-Q?",
  "vendor_events": false
}

Non-streaming JSON response

{
  "model": "sonnet",
  "input": "Summarize the latest CPI release.",
  "stream": false,
  "vendor_events": false
}

Validated JSON plus grounded analysis

{
  "model": "sonnet",
  "input": "Extract NVIDIA's latest quarterly revenue.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "quarterly_revenue",
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "revenue_usd"
        ],
        "properties": {
          "revenue_usd": {
            "type": "number"
          }
        }
      },
      "strict": true
    }
  },
  "vendor_events": false
}

Ground on an uploaded file

{
  "model": "opus",
  "input": "Compare this filing's risk factors to Q3.",
  "sources": {
    "file_ids": [
      "file_01HZ..."
    ]
  },
  "vendor_events": false
}

Run the turn as one of your agents

{
  "model": "sonnet",
  "input": "Assess this opportunity for our program.",
  "agent_id": "9c1d2e3f-4a5b-4c7d-8e9f-0a1b2c3d4e5f",
  "vendor_events": false
}

Responses

200

When stream is true: SSE stream of response events, each prefixed with data: . When stream is false (default, matching OpenAI’s spec): a single JSON body matching the terminal response.completed payload.

One of: discriminator: type

object

type

required

string

Allowed values: response.created

response

required

object

required

string

object

required

string

Allowed values: response

created_at

required

integer

model

required

string

status

required

string

Allowed values: in_progress

output

required

Array

object

type

required

string

Allowed values: response.content_part.done

item_id

required

string

content_index

required

integer

part

required

object

type

required

string

Allowed values: output_text

text

required

string

annotations

required

Array<object>

object

type

required

string

Allowed values: url_citation

start_index

required

Byte offset of the citation marker (e.g. [1]) in the output-text content part’s text value.

integer

end_index

required

Exclusive byte offset of the end of the citation marker in the output-text content part’s text value.

integer

url

required

URL of the source backing the citation.

string

title

required

Human-readable title of the source.

string

cited_text

Verbatim excerpt from the source (or, for an image source, the caption or surrounding context) that supports the cited claim. Use this to render tooltips or footnotes without re-fetching the source.

string

Terminal response.completed payload (returned only when stream: false).

object

Example

{
  "id": "resp_4b2c0e7f9a1d4f6a8c0e1b2d3a",
  "object": "response",
  "created_at": 1762800000,
  "status": "completed",
  "model": "sonnet",
  "request_id": "11111111-2222-3333-4444-555555555555",
  "output": [
    {
      "id": "msg_8d2a3f0e6b1c4d5f7a9b0c2e1d",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "{\"summary\":\"NVIDIA reported record $35.1 billion in Q3 FY2026 revenue.\",\"revenue_usd\":35100000000}",
          "annotations": []
        }
      ]
    }
  ],
  "route": "research",
  "timings": {
    "total_ms": 12450
  }
}

400

Invalid request (missing input, malformed params, etc.)

application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example ^generated

{
  "error": {
    "message": "example",
    "type": "example",
    "code": "example"
  }
}

401

Unauthorized

application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example ^generated

{
  "error": {
    "message": "example",
    "type": "example",
    "code": "example"
  }
}

402

Credit exhausted. The error envelope includes reset_at (ISO-8601) so clients can compute backoff without parsing the prose message.

application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example

{
  "error": {
    "message": "You're out of credits until June 1.",
    "type": "credit_exhausted",
    "code": "credit_exhausted",
    "reset_at": "2026-06-01T00:00:00.000Z"
  }
}

404

A referenced resource doesn’t exist or isn’t accessible to the caller: agent_not_found (bad agent_id), project_not_found (bad project_id), or request_not_found (bad request_id).

application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example

{
  "error": {
    "message": "Agent not found",
    "type": "invalid_request_error",
    "code": "agent_not_found"
  }
}

409

The request cannot accept this turn: either another turn is still running, or the selected agent belongs to a different project than a moved request.

application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example

{
  "error": {
    "message": "This agent isn't available in the request's current project. Move the request or choose an agent from that project.",
    "type": "invalid_request_error",
    "code": "agent_project_mismatch"
  }
}

500

Server error (e.g. missing API keys)

application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example ^generated

{
  "error": {
    "message": "example",
    "type": "example",
    "code": "example"
  }
}

Create a grounded response

Authorizations

Request Body required

Examples

Responses

200

Example

400

Example generated

401

Example generated

402

Example

404

Example

409

Example

500

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated