Skip to content
Cemented AI

Overview

Cemented Grounded Search API 1.0.0

Section titled “Cemented Grounded Search API 1.0.0”

The Cemented Grounded Search API runs a Plan → Collect → Process → Analyze pipeline against the live web (and any uploaded files) and returns a cited answer in the OpenAI Responses API shape. It is wire-compatible with the official OpenAI SDKs — point your OpenAI client at https://www.cemented.ai/v1, swap the model name for sonnet or opus, and existing code that calls /v1/responses keeps working.

Authentication

Send your Cemented API key as Authorization: Bearer <key>. The OpenAI SDKs already do this when you pass it as api_key/apiKey — no extra wiring required. x-api-key: <key> is also accepted for clients that don’t follow the OpenAI convention. Keys can be provisioned in the dashboard.

Drop-in usage with the OpenAI SDK

Python

from openai import OpenAI

client = OpenAI(
    api_key="ck-...",
    base_url="https://www.cemented.ai/v1",
)

response = client.responses.create(
    model="sonnet",
    input="What did NVIDIA report in its latest 10-Q?",
    # Opt out of Cemented-specific stream events so the SDK only sees
    # OpenAI-shape events. Skip this if you want pipeline progress.
    extra_body={"vendor_events": False},
)

print(response.output_text)

Node / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "ck-...",
  baseURL: "https://www.cemented.ai/v1",
});

const response = await client.responses.create({
  model: "sonnet",
  input: "What did NVIDIA report in its latest 10-Q?",
  // @ts-expect-error — Cemented-specific extension
  vendor_events: false,
});

console.log(response.output_text);

response.output_text in these examples is an OpenAI SDK convenience accessor assembled from the response’s output-message content. The raw HTTP response has no top-level output_text field; clients using fetch should read the text property from an output_text content part in response.output.

Streaming

Pass stream: true (streaming is opt-in, matching OpenAI’s spec) and consume the SSE stream with the SDK’s stream helpers exactly as you would with OpenAI:

const stream = await client.responses.create({
  model: "sonnet",
  input: "Summarize the latest CPI release.",
  stream: true,
});
for await (const event of stream) {
  if (event.type === "response.output_text.delta") process.stdout.write(event.delta);
}

Citations

For report output, every output_text content part carries a url_citation annotation for each inline [N] marker, with start_index / end_index byte offsets, the source url / title, and the verbatim cited_text excerpt. Structured output returns clean serialized JSON in the standard output-text content. Its field-level provenance stays on the persisted run and is rendered when that request is opened in Cemented. See the Working with citations guide on the docs site for the annotation schema and recipes that expand markers into footnotes or HTML tooltips.

Structured output

Set text.format.type to json_schema and include a closed JSON Schema, matching the OpenAI Responses request shape, when downstream code needs a structured response. OpenAI SDK Zod/Pydantic helpers serialize to this shape. The initial portable schema profile supports closed objects with every property required, homogeneous arrays, scalar types and constraints, common string formats, nullable two-branch anyOf, and acyclic local $defs or definitions references. Unsupported keywords, general unions, tuples, open objects, and recursive or external references are rejected before a run is created. The structured JSON is the complete answer: there is no required or synthetic analysis field. Free-form string fields can contain the same long-form grounded prose and citation syntax used by report output, so a result can contain zero, one, or many analysis-style fields. The terminal response places a deterministic, wrapper-free JSON serialization in the standard Responses output message, so OpenAI SDK parsing helpers work without a Cemented-specific response shape. When the request is opened in Cemented, verified field provenance renders from the run’s canonical persisted tree. Strings keep their native schema shape and use the ordinary citation grammar directly. Strings with enum, const, or format remain exact, ungrounded machine values. Literal quotation marks are preserved; only verified quote delimiters and known snippet markers are removed from prose strings. Numeric fields reference a server-verified computed snippet whose every named input resolves to exact, verified source evidence and participates in the expression. The server validates the clean result, including supported string formats, against the caller’s schema before returning it. Calculations use decimal arithmetic and must equal the native JSON number exactly; explicit rounding is supported. The completed JSON is not scanned as prose for citations or calc markup.

Capability discovery: /v1/models

GET /v1/models returns OpenAI-shape model entries plus capability metadata (context_length, max_output_tokens, supports_streaming, search_providers, grounded) so callers can pick a model programmatically. _maps_to exposes the underlying Anthropic Claude model the grounded pipeline runs on.

Cemented extensions

Two request fields and one error field are Cemented-only:

  • vendor_events (default true) — when false, suppresses response.pipeline_stage, response.source_texts, and the web_search_call output item so the official OpenAI SDK only sees the events it natively models. Set false for drop-in usage when you don’t want to surface pipeline progress.
  • stream (default false, matching OpenAI’s spec) — pass true to receive an SSE stream of response events instead of a single JSON body.
  • error.reset_at — ISO-8601 timestamp on credit_exhausted failures, for Retry-After-style backoff.

Errors otherwise follow the OpenAI shape: { "error": { "message", "type", "code" } }.

Information

  • OpenAPI version: 3.1.0

Operations

Section titled “ Operations ”
POST
/v1/search
POST
/v1/contents
GET
/v1/models
GET
/v1/agents
POST
/v1/files
POST
/v1/grounded-artifacts/validate
POST
/v1/grounded-artifacts
POST
/v1/responses

Authentication

Section titled “ Authentication ”

BearerAuth

Section titled “BearerAuth ”

Send your Cemented API key as Authorization: Bearer <key>. The OpenAI SDKs do this automatically when you pass api_key/apiKey.

Security scheme type: http

ApiKeyHeader

Section titled “ApiKeyHeader ”

Alternative to Authorization: Bearer for clients that don’t follow the OpenAI convention.

Security scheme type: apiKey

Header parameter name: x-api-key