Responses

Overview

Use the Responses API for Calypso RAG whenever possible. It supports rich, structured streaming events, grounded source metadata, conversation state, and maps well to modern chat UIs.

• Endpoint: POST /responses
• Base URL: https://api.calypso.so/v1
• Authentication: Bearer project API key — see Authentication

Basic request

Minimal JSON request:

{
  "model": "calypso-rag-agent",
  "input": "What is our refund policy?"
}

Python (non-streaming)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CALYPSO_API_KEY",
    base_url="https://api.calypso.so/v1"
)

resp = client.responses.create(
    model="calypso-rag-agent",
    input="What is our refund policy?"
)

print(resp.output_text)

Streaming (recommended)

Set stream=True to receive SSE events as the agent generates output.

Python (streaming)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CALYPSO_API_KEY",
    base_url="https://api.calypso.so/v1"
)

stream = client.responses.create(
    model="calypso-rag-agent",
    input="What is our refund policy?",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

JavaScript (Node.js streaming)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CALYPSO_API_KEY,
  baseURL: "https://api.calypso.so/v1",
});

const stream = await client.responses.create({
  model: "calypso-rag-agent",
  input: "What is our refund policy?",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

Grounded sources

Calypso RAG returns grounded source metadata alongside the answer so you can render citations. Sources surface through the response output in OpenAI-native form:

• Inline citations — annotation objects on the output_text content, anchored to the answer by start_index / end_index character spans.
• Source list — the file_search_call output item, whose results[].attributes carry a stable source_index and a display-ready label for each retrieved source.
• Status metadata — a compact metadata._aicore block reporting retrieval_status and grounded_sources_state.

See Citations and sources for the full schema, JSON examples, the request-level citation_compat / sources_appendix options, and rendering guidance. See Playground grounding states for how to interpret available, hidden, missing, and none.

Attaching files

You can attach a previously uploaded file as input by passing its file_id so the answer is grounded in that document:

{
  "model": "calypso-rag-agent",
  "input": [
    { "type": "input_text", "text": "Summarize the attached contract." },
    { "type": "input_file", "file_id": "file_abc123" }
  ]
}

Uploads are bucket-backed. See Knowledge Buckets and the Upload API for how to create durable knowledge.

Stateful conversations

The Responses API supports OpenAI-style statefulness on top of Calypso's conversation store. Continue a thread by passing either conversation or previous_response_id — not both:

resp = client.responses.create(
    model="calypso-rag-agent",
    input="And what about international orders?",
    previous_response_id=previous_resp.id
)

Selecting answer effort

Use the OpenAI-standard reasoning.effort field to control how much effort calypso-rag-agent puts into an answer. Allowed values are minimal, low, medium, and high, which map to the Fast, Medium, and Extended answer tiers.

resp = client.responses.create(
    model="calypso-rag-agent",
    input="What is our refund policy?",
    reasoning={"effort": "high"}
)

The tier that actually ran is echoed back in resp.reasoning.effort (capped to your plan's ceiling). See Controlling answer effort for the full mapping and the deprecated metadata.response_policy fallback.

Notes

• Handle disconnects and retries gracefully.
• If the user cancels, abort the request and stop rendering deltas.