Project API keys
Why API keys matter
In Calypso RAG, project API keys define the workspace context for requests. The key determines which knowledge buckets, default agent policy, and named calypso-rag-agent variants the caller can use.
You need a project API key for:
- Playground requests
- MCP Server clients
- the knowledge Upload API
- n8n credentials
- OpenAI-compatible
/v1/responsescalls
Where to manage them
Open Project → API Keys in your Calypso RAG workspace, or go there directly:
Keep this surface close when testing. If a request behaves differently between Playground, MCP, and direct API calls, first confirm they are using the same active key.
Important concepts
Workspace-scoped
Keys belong to the current project or workspace. This keeps buckets, agent policies, named profiles, and integrations aligned to one scope.
Agent-variant discovery
The same key is used to list available RAG agent variants. A key for one workspace should not expose another workspace's calypso-rag-agent:{profile_id} models.
Bucket-aware uploads
Upload calls made with a key must still include a bucket destination when creating durable knowledge. The key authorizes the workspace; bucket fields choose where the file lands.
Active keys only
Only active keys should be used in real testing or production integrations.
Default web key
Some hosted web flows prefer the protected default web key when it exists. For backend, MCP, and automation use cases, create a dedicated project key you can rotate without disrupting the web surface.
Common issues
Playground cannot send
Usually one of these is true:
- no active key exists
- the wrong key is selected
- the selected key is no longer active
The docs example works differently in your app
Check:
- the exact key being used
- the correct base URL for the environment
- whether the target model id is the default agent or a named variant
- whether the target agent is connected to the expected buckets