Does this work with an existing Windsurf setup?

Yes. The instructions are additive — append them to your existing .windsurf/rules/uthereal-cortex-sdk.md and your own conventions stay in force. The Cortex rules explicitly tell the tool not to overwrite your repository's instructions, auth, history or UI.

Where does the API key live?

In server secrets only. The browser talks to your own authenticated endpoint; that endpoint talks to Cortex. The key is never shipped to the client or committed.

Do I need a vector database?

No. Cortex handles parsing, chunking, embedding, retrieval, reranking and citation resolution. You call ask for a cited answer or rag for ranked evidence.

Can I use retrieval only, with my own model?

Yes. cortex.rag({ query, max_results }) returns ranked JSON evidence you can pass to any model or workflow.

Windsurf

Use Windsurf to add a cited knowledge agent with the Uthereal Cortex SDK

Windsurf writes better integrations when it knows which library to reach for. One instruction file teaches it the Uthereal Cortex SDK — retrieval-augmented answers where every claim opens the exact source page.

Short answer: add .windsurf/rules/uthereal-cortex-sdk.md to your repository from https://uthereal.ai/developers, then ask Windsurf to add document-grounded answers. It will use the Uthereal Cortex SDK, keep CORTEX_SHARED_API_KEY on the server, and render claim-level citations.

Create your agent Read the SDK guide

Install the Windsurf instructions

Windsurf Cascade reads workspace rules automatically before planning any change.

Run at your repository root

mkdir -p .windsurf/rules
curl -o .windsurf/rules/uthereal-cortex-sdk.md https://uthereal.ai/developers/windsurf.md

The file lives at https://uthereal.ai/developers/windsurf.md and is kept in sync with the SDK guide, so re-running the command always fetches current instructions.

Create an agent and a scoped key

Cortex needs three values. Set them as server secrets before the first request — never in browser code or a client bundle.

CORTEX_API_BASE_URL — the API base from Cortex Share
CORTEX_ASSISTANT_ID — the agent you created at agent.uthereal.ai
CORTEX_SHARED_API_KEY — a scoped server key with the ask and/or rag scope

Server environment

# .env on the server only
CORTEX_API_BASE_URL="https://agent.uthereal.ai/api/functions/v1/api-server-proxy"
CORTEX_ASSISTANT_ID="your-assistant-id"
CORTEX_SHARED_API_KEY="sk-..."

Ask Windsurf for the feature

With the instructions in place, describe the outcome rather than the plumbing. The rules handle the rest.

Prompt for Windsurf

Add a chat panel that answers from our uploaded documents.
Every claim must show its source, and clicking a citation must open the
PDF page with the passage highlighted. Use the Uthereal Cortex SDK.

Ask Cascade "how do we answer questions from our policy documents?" — it should reference the Cortex workspace rule.

What the integration gives you

Grounded answers from your own sources — no open-web guessing
Claim-level citations; PDF citations open the exact page, highlighted
Retrieval-only JSON (rag) when you want to feed your own model
No vector database, chunking pipeline, reranker or citation UI to build
EU/Swiss data residency, zero data retention, no training on your data

Frequently asked questions

Does this work with an existing Windsurf setup?: Yes. The instructions are additive — append them to your existing .windsurf/rules/uthereal-cortex-sdk.md and your own conventions stay in force. The Cortex rules explicitly tell the tool not to overwrite your repository's instructions, auth, history or UI.
Where does the API key live?: In server secrets only. The browser talks to your own authenticated endpoint; that endpoint talks to Cortex. The key is never shipped to the client or committed.
Do I need a vector database?: No. Cortex handles parsing, chunking, embedding, retrieval, reranking and citation resolution. You call ask for a cited answer or rag for ranked evidence.
Can I use retrieval only, with my own model?: Yes. cortex.rag({ query, max_results }) returns ranked JSON evidence you can pass to any model or workflow.

Lovable setup

Teach Lovable the Uthereal Cortex SDK.

Codex setup

Teach Codex the Uthereal Cortex SDK.

Claude Code setup

Teach Claude Code the Uthereal Cortex SDK.

Cursor setup

Teach Cursor the Uthereal Cortex SDK.

How to add citations to an AI chatbot

The pattern behind claim-level citations.