NormaHub
NormaHub knowledge base

Connecting Cursor

Your NormaHub API key in Cursor: Override Base URL, adding models, the Verify check and typical error fixes.

1. What you need

Cursor can drive chat and agent through your own key of an OpenAI-compatible provider. You need: a paid Cursor plan, a NormaHub API key from the dashboard, and exact model IDs from the catalog. Create a dedicated key with a spend limit: the IDE generates many requests, and an unlimited key can surprise you at billing time. Russian version: Подключение Cursor.

2. Models settings

Open Cursor Settings (Ctrl/Cmd + ,) → Models. Enable OpenAI API Key and paste the NormaHub key. Then enable Override OpenAI Base URL and set the NormaHub address. Field labels depend on the Cursor version, but the idea is the same: key plus overridden base address.

OpenAI API Key:     YOUR_API_KEY              # key from the NormaHub dashboard
Override Base URL:  https://api.normahub.cc/v1  # must end with /v1
Add Model:          MODEL_ID                    # exact ID from the catalog

Use Add Model for the IDs you need — e.g. a strong model for refactors and a cheap one for small edits. Switching between them in chat is practical savings: never run the flagship to fix typos.

3. The Verify check

Press Verify next to the settings: Cursor requests the model list with your key and confirms it works. If the list is empty or errors — stop here and fix the connection; further steps fail with the same 401 in less readable form. An independent check is curl to /v1/models with your Bearer key.

After success open a new chat, pick the added model from the dropdown and send a test question about your project. Compare the charge in the dashboard history: request price depends on the model and context length, details are in the token cost guide.

4. Nuances and limits

Your key covers chat and agent with the selected model, but not everything in Cursor: Tab completion and some built-in features keep going through Cursor models. Budget accordingly — the NormaHub bill grows only from requests through your key. Cursor Zero Data Retention does not apply to your own key: processing is governed by the model provider policies.

Cursor assembles project context itself and it is not small: long sessions over a large project cost noticeably. Keep the errors guide at hand: 402 means empty balance or exhausted key limit, 429 means rate limit — both fixed in the dashboard within a minute.

5. When something breaks

«Invalid API Key» — mistyped, revoked, or pasted into the wrong field; Cursor caches keys aggressively, restart the IDE after replacing. «Model not found» — the ID is not exact (case and dashes matter) or the model is unavailable to your key. Empty chat without an error — check that the added model, not a built-in one, is selected. On errors verify balance and available models in the dashboard.

6. If your version looks different

Cursor renames these settings between releases: Models → API Keys, Override OpenAI Base URL, or a Custom Provider / OpenAI-compatible provider block. The values stay the same: your NormaHub key, https://api.normahub.cc/v1 with trailing /v1, and the exact model ID from the catalog. If there is no Verify button, save and send a real chat message with the added model selected — that is the verification. Never use the dashboard or homepage URL as the Base URL.

To return to Cursor built-in models temporarily, disable the OpenAI API Key toggle or the Base URL override — no need to delete the values.

7. Privacy: where your key goes

All chat and agent requests are routed through Cursor servers for final prompt building, so the key travels with each request over an encrypted connection and is not persisted after the request completes. Cursor Zero Data Retention does not apply to your own key: processing is governed by the model provider policies. If your team relies on Zero Data Retention, use Cursor built-in models instead.

8. Troubleshooting checklist

  • No pasted spaces — re-paste the key into the OpenAI API Key field, not into another provider field.
  • Trailing /v1 present — https://api.normahub.cc/v1, letter by letter.
  • Model added and selected — Add Model with the exact catalog ID, then pick it in the chat dropdown, not Auto.
  • Independent curl check — GET /v1/models with your Bearer key before blaming the IDE.
  • Paid plan active — custom endpoints require a paid Cursor subscription.
  • Restart after key change — Cursor caches keys; restart the IDE after replacing.

Billing split to remember: your provider bills the model cost, Cursor built-ins bill through Cursor. Keep the errors guide at hand for 401/402/429.

Частые вопросы

Do I need a paid Cursor plan for a custom API?

Yes, a custom API endpoint requires a paid Cursor subscription. On the free tier the custom provider fields may be unavailable — check Settings → Models in your version.

Base URL with or without /v1?

For Cursor — with trailing /v1: https://api.normahub.cc/v1. Without it Cursor cannot find /chat/completions and Verify fails. Claude Code is the opposite: its address goes without /v1.

Which models do I add to Cursor?

Exact model IDs from the NormaHub catalog or from GET /v1/models with your key. After adding, press Verify: Cursor fetches the list itself and confirms the key works.

Why does Verify fail?

Three typical causes: the key is invalid or revoked (401), the Base URL lacks /v1, or no network route to api.normahub.cc. Verify the key with curl to /v1/models first, then compare the address letter by letter.

Will Tab autocomplete use my key?

No. Fast Tab completion uses Cursor built-in models. Your key serves chat and agent with the model you select.

Does my key cover Auto, Cloud agents, or the Cursor CLI?

No. A custom key covers local Chat and Agent with the model you select. Tab completion, Auto routing, Cloud and Background Agents, Automations, the Cursor CLI, and Cursor API/SDK calls keep using Cursor-supplied models.

My Cursor has no Verify button — what now?

Recent Cursor builds removed the Verify button or moved the flow under a Custom Provider block. Enter the same three values (key, https://api.normahub.cc/v1, exact catalog model ID), save, then verify with a real chat message plus a curl call to /v1/models.

Will my API key leave my device?

The key is sent with each request because Cursor builds the final prompt on its servers, over an encrypted connection, and it is not persisted after the request completes. Cursor Zero Data Retention does not extend to third-party keys.