Authentication

Authenticate Calypso RAG's OpenAI-compatible API with a project API key sent as a Bearer token.

Overview

Every request to the OpenAI-compatible API is authenticated with a project API key, sent as a Bearer token in the Authorization header. The key determines the workspace context for the request: which knowledge buckets, default agent policy, and named calypso-rag-agent variants the caller can use.

Don't have a key yet? Join Calypso RAG for free or sign in.

Get an API key

Open Project → API Keys in your Calypso RAG workspace, or go there directly:

Open Project API Keys

Keys are workspace-scoped: they belong to the current project and keep buckets, agent policies, named profiles, and integrations aligned to one scope. Only active keys should be used in real testing or production. For more on key management and agent-variant discovery, see Project API keys.

Authorization header

Send the key as a Bearer token:

Authorization: Bearer YOUR_CALYPSO_API_KEY

OpenAI SDK

The OpenAI SDKs handle the header for you when you set api_key and base_url:

from openai import OpenAI

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

import OpenAI from "openai";

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

Raw HTTP

curl -X POST "https://api.calypso.so/v1/responses" \
  -H "Authorization: Bearer $CALYPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "calypso-rag-agent",
    "input": "Summarize the grounded knowledge available in this workspace."
  }'

Security best practices

Treat API keys like passwords — never commit them to source control or expose them in client-side code.
Load keys from environment variables or a secrets manager.
Create a dedicated project key for backend, MCP, and automation use cases so you can rotate it without disrupting hosted web flows.
Rotate or deactivate keys immediately if you suspect they have leaked.

Common issues

If a request behaves differently between the Playground, MCP, and direct API calls, first confirm they all use the same active key and the same base URL. A key for one workspace will not expose another workspace's calypso-rag-agent:{profile_id} models.

Overview

Responses