I Connected Cursor to OpenRouter. Here's a Script to Verify It Before You Trust the Editor.

Why I Wanted to Verify Outside the Editor First

Cursor's error messages when a custom API connection fails aren't always helpful — sometimes you get a clear error, sometimes a mode just quietly stops producing useful output with no obvious signal about why. Before trusting my Cursor OpenRouter setup inside the editor, I wanted to confirm the connection actually worked from a plain script first, so I'd know whether any future weirdness was Cursor-specific or an actual API problem.

The Cursor-Specific Endpoint

OpenRouter provides a dedicated endpoint built specifically to handle Cursor's request format: https://openrouter.ai/api/v1/cursor — not the standard /api/v1 you'd use for a generic OpenAI compatible API call. This is currently in beta, and it's worth checking OpenRouter's own API documentation for the current state before assuming behavior is fully stable.

The Verification Script

import requests
import json

OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"
CURSOR_ENDPOINT = "https://openrouter.ai/api/v1/cursor/chat/completions"

def verify_cursor_endpoint(model_id, api_key=OPENROUTER_API_KEY):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": model_id,
        "messages": [{"role": "user", "content": "Reply with exactly: connection ok"}],
    }
    response = requests.post(CURSOR_ENDPOINT, headers=headers, json=payload, timeout=15)

    print(f"Status: {response.status_code}")
    if response.status_code == 200:
        content = response.json()["choices"][0]["message"]["content"]
        print(f"Response: {content}")
        return True
    else:
        print(f"Error body: {response.text}")
        return False

if __name__ == "__main__":
    models_to_check = [
        "anthropic/claude-3.5-sonnet",
        "openai/gpt-5.6-mini",
    ]
    for model in models_to_check:
        print(f"\n--- Checking {model} ---")
        verify_cursor_endpoint(model)

Running this confirms two things independently of Cursor's UI: that your OpenRouter API key is valid and has access to the models you're planning to use, and that the Cursor-specific endpoint itself is responding correctly for those model IDs. If this script works and Cursor still misbehaves, you've isolated the problem to Cursor's client behavior rather than your credentials or endpoint configuration.

Configuring Cursor Itself

Once the script confirms the connection works:

1. Open Cursor → Settings → Models
2. Enable "Override OpenAI Base URL"
3. Enter https://openrouter.ai/api/v1/cursor (not the plain /api/v1 path)
4. Paste your OpenRouter key into the API key field
5. Add a custom model using the same model ID you verified in the script
6. Click Verify

Where This Actually Got Murky

Chat-based modes worked immediately once configured this way. Agent mode was less consistent — Cursor's support for custom API connections hasn't extended identically across every mode historically, and I found conflicting information even in adjacent documentation about which modes fully support this at any given time. If Agent mode seems to silently stop being useful rather than throwing a clear error, that's a known rough edge in an integration that's actively evolving, not necessarily something wrong with your setup — which is exactly why running the verification script first is worth the five minutes; it tells you definitively whether the problem is upstream of Cursor.

Why Bother With This Instead of Cursor's Native Providers

Cursor supports a handful of providers natively through its own key-based setup. Routing through an AI API gateway like OpenRouter instead gets you access to a much wider set of OpenRouter models through one key, plus automatic failover if a specific provider has an outage, and centralized usage tracking if you're managing this across a team rather than just yourself.

If You're Setting This Up Yourself

• Run a verification script against the API directly before assuming a Cursor problem is a connection problem
• Use the Cursor-specific endpoint path, not OpenRouter's general base URL — they don't handle the request format identically
• Test in a simpler mode (chat/ask) before troubleshooting Agent mode specifically, since support levels aren't guaranteed to match Testing the Same Pattern Elsewhere

Once I had this verification pattern working, I used a similar approach — hitting an API directly with a small script before trusting an editor's UI — to sanity-check a comparable setup through RouteAI for a different project, unrelated to Cursor specifically. That's a separate decision worth checking on its own terms; the verification pattern above is the actually reusable part, regardless of which gateway you're pointing an editor at.

TL;DR: Before trusting Cursor's UI when a custom OpenRouter connection misbehaves, verify the endpoint and key work with a plain script first — that isolates whether a problem is your API configuration or Cursor's client behavior in a specific mode. Endpoint must be /api/v1/cursor, not the standard /api/v1. Verification script above.

Check out the tool I covered here: www.fastrouteai.com