Chat Completions

Legacy-compatible endpoint for Calypso RAG with classic message-based streaming.

Overview

Use Chat Completions when you need a classic message-based interface that is compatible with older OpenAI client patterns. For new integrations, prefer the Responses API, which exposes richer grounding metadata and conversation state.

To call this API you need an API key. Join Calypso RAG for free or sign in.

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

Basic request

{
  "model": "calypso-rag-agent",
  "messages": [
    { "role": "user", "content": "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.chat.completions.create(
    model="calypso-rag-agent",
    messages=[
        {"role": "user", "content": "What is our refund policy?"}
    ]
)

print(resp.choices[0].message.content)

Streaming

Set stream=True to receive incremental deltas (chunked).

Python (streaming)

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="calypso-rag-agent",
    messages=[
        {"role": "user", "content": "What is our refund policy?"}
    ],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta and getattr(delta, "content", None):
        print(delta.content, 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.chat.completions.create({
  model: "calypso-rag-agent",
  messages: [{ role: "user", content: "What is our refund policy?" }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices?.[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

Citations

Grounded answers include citation annotations on choices[0].message.annotations[], using OpenAI's nested url_citation shape (file sources are mapped to signed access URLs, with the filename as the title). The message content also carries a plain-text "Sources:" appendix, and streaming delivers annotations in a final delta.annotations chunk.

See Citations and sources for the full annotation schema and examples. For structured file search results and grounding metadata, use the Responses API.

Selecting answer effort

Use the OpenAI-standard top-level 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.chat.completions.create(
    model="calypso-rag-agent",
    messages=[{"role": "user", "content": "What is our refund policy?"}],
    reasoning_effort="high"
)

The requested tier is capped to your plan's ceiling. See Controlling answer effort for the full mapping and the deprecated metadata.response_policy fallback.

Responses

Citations & sources