OpenAI-Compatible API

Calypso RAG exposes an OpenAI-compatible API with Responses and Chat Completions endpoints, so you can point the standard OpenAI SDKs at Calypso and reuse familiar patterns.

Overview

Calypso RAG exposes an OpenAI-compatible API so you can get grounded, cited answers from your knowledge buckets using the tools you already know.

Because it is OpenAI-compatible, you can point the standard OpenAI SDKs (Python, Node.js, and others) at Calypso's base URL and reuse familiar model selection, streaming, and conversation patterns. The hosted RAG agent is exposed as the model calypso-rag-agent (with optional named variants).

To call this API you need an active project API key. Join Calypso RAG for free or sign in to get one.

Base URL

https://api.calypso.so/v1

API overview

The API offers two main OpenAI-compatible endpoints, plus model discovery:

Endpoint	Description	Documentation
`POST /responses`	Create a response (streaming or non-streaming) with the modern, recommended API surface	Responses API →
`POST /chat/completions`	Create a chat completion using the classic, legacy-compatible message interface	Chat Completions API →
`GET /models`	Discover the `calypso-rag-agent` variants available to your API key	Model IDs and profiles →

Authentication

All requests are authenticated with a project API key sent as a Bearer token. See the Authentication guide for how to obtain and use keys securely.

Using the OpenAI SDK

Point any OpenAI SDK at Calypso's base URL and pass your project API key:

from openai import OpenAI

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

response = client.responses.create(
    model="calypso-rag-agent",
    input="Summarize the grounded knowledge available in this workspace."
)

print(response.output_text)

With that base URL:

client.responses.create(...) hits Calypso's Responses endpoint
client.chat.completions.create(...) hits Calypso's Chat Completions endpoint
client.models.list() discovers the available model IDs

Choosing a model

Model	What it is
`calypso-rag-agent`	The default grounded RAG agent for the workspace tied to your API key
`calypso-rag-agent:{profile_id}`	A named agent variant that can point at different buckets and policy

See Model IDs and profiles for how variants resolve and which buckets they search.

Responses vs Chat Completions

Both endpoints run through the same core Calypso RAG pipeline, but they behave differently at the interface level.

Use Responses when possible

The Responses API is the better fit for new integrations because it supports:

richer, structured streaming events
conversation objects and previous_response_id
structured citations and sources (annotations, file search results, grounding metadata)
attaching uploaded files as input
modern OpenAI client patterns

Use Chat Completions for older integrations

The Chat Completions API is useful when:

you already have legacy OpenAI client code
your UI expects classic message arrays
you only need token-style delta streaming

Controlling answer effort

Calypso RAG accepts the OpenAI-standard effort control on both endpoints:

Chat Completions: the top-level reasoning_effort field
Responses: the reasoning.effort field

Allowed values are minimal, low, medium, and high. They map onto the same answer tiers you can pick in the Playground response mode:

`reasoning_effort`	Response mode	Answer model
`minimal` / `low`	Fast	Gemini Flash Lite
`medium`	Medium	Gemini Flash
`high`	Extended	Gemini Pro

Higher effort produces stronger answers at higher latency and cost. The requested tier is capped to your plan's ceiling, and on the Responses API the tier that actually ran is echoed back in the reasoning.effort field of the reply.

The older metadata.response_policy (and metadata._aicore.response_policy) channel is deprecated but still honored. Prefer reasoning_effort / reasoning.effort, which work with the stock OpenAI SDKs and are applied identically on both endpoints. When both are present, reasoning_effort / reasoning.effort wins.

Next steps

Project API keys

Authentication