Integration Guide: Connecting Cursor to HeliosX

This guide explains how to configure Cursor to use the HeliosX API gateway as its backend. Cursor is an AI-powered code editor built on VS Code, featuring an agent mode for autonomous coding, tab completions, inline edits, and more.

By routing Cursor through HeliosX, you get access to hundreds of models through a single API key, automatic provider failover, and centralized usage tracking.

Quick Start

Cursor supports HeliosX through its Override OpenAI Base URL feature. This routes requests from Cursor's OpenAI provider override through HeliosX's OpenAI-compatible endpoint.

Step 1: Get Your HeliosX API Key

1. Sign up or log in at HeliosX
2. Navigate to your API Keys page in the dashboard
3. Create a new API key
4. Copy your key (starts with sk-)

Step 2: Configure Cursor

1. Open Cursor Settings (gear icon or Cmd/Ctrl + ,)
2. Navigate to Models, then expand the API Keys section
3. Toggle on OpenAI API Key, then:
   • Paste your HeliosX API key into the OpenAI API Key field
   • Toggle on Override OpenAI Base URL and set it to:

https://api.heliosx.ai/v1/cursor

Step 3: Add Models

After connecting, add the models you want to use. In the Models section, click + Add model and enter a HeliosX model ID:

anthropic/claude-opus-4.8
anthropic/claude-opus-4.7
anthropic/claude-opus-4.6
google/gemini-3.5-flash
openai/gpt-5.5

Step 4: Select a Model

Open the model picker in the chat or agent panel and select one of the models you added. Your requests will now route through HeliosX.

How It Works

HeliosX exposes a dedicated Cursor endpoint at /v1/cursor/chat/completions that normalizes Cursor's request format into the standard OpenAI Chat Completions format before routing. When Cursor sends a Responses API payload (with an input field instead of messages), the endpoint transparently routes it through the Responses pipeline and converts the result back into Chat Completions format. When you configure Cursor to use HeliosX's base URL, all chat and agent requests are routed through HeliosX, which then forwards them to the appropriate upstream provider.

The endpoint handles each model family transparently:

• Anthropic (Claude) and Google (Gemini) Responses payloads are converted to Chat Completions and routed through the shared converters, so tool results and multi-turn tool calls are preserved correctly.
• OpenAI (GPT) and other Responses payloads use the native Responses pipeline with Chat Completions-compatible output.
• Standard Chat payloads (with messages) are forwarded directly.

Reasoning models are fully supported: reasoning summaries are preserved and streamed back in Chat Completions format so Cursor renders them inline. For thinking models that spend several seconds before emitting visible tokens, the endpoint sends SSE keep-alive heartbeats during provider silence so Cursor keeps the connection open instead of showing “reconnecting.”

Why Use HeliosX with Cursor?

Access to Hundreds of Models

Cursor's built-in BYOK only supports a handful of providers. With HeliosX, you get access to hundreds of models across dozens of providers — all through the single OpenAI provider override.

Provider Failover

If one provider is unavailable or rate-limited, HeliosX automatically routes to another, keeping your coding sessions uninterrupted.

Organizational Controls

For teams, HeliosX provides centralized budget management. Set spending limits, allocate credits, and monitor usage across developers using Cursor from your HeliosX dashboard.

Usage Visibility

Track which models your team uses, monitor costs in real-time, and understand usage patterns from a single dashboard — regardless of the underlying provider.

Limitations

• Tab completions are not affected by BYOK settings; they always use Cursor's built-in models.
• Auto and Composer 2 modes may not be routed through your API key. Check Cursor's docs for current behavior.
• Only models accessible via HeliosX's OpenAI-compatible endpoint will work. Most chat and reasoning models are supported, including thinking models that stream reasoning summaries.

Troubleshooting

Resources

• Cursor Documentation
• Cursor BYOK Help
• Chat Completions API
• Authentication