Cursor lets you bring your own key and point its chat and agent features at any OpenAI-compatible endpoint. That means you can route Cursor through a gateway like Zivv, pick from 100+ models with one key, and pay per token instead of per seat. The setup is two fields — a base URL and a key — but those two fields are also where almost every failed configuration happens. This guide covers the exact values, how to pick models, and the pitfalls that produce instant verification errors.
How Cursor's Custom API Support Works
Cursor speaks the OpenAI protocol for chat and agent requests. When you enter your own API key and enable the base URL override, those requests go to your endpoint instead of Cursor's default routing. The gateway receives a standard /chat/completions call, forwards it to the model you named, and returns a standard response. Cursor cannot tell the difference.
Two caveats worth knowing before you start:
- Some Cursor features run on Cursor's own infrastructure regardless of your key. Tab autocomplete is the usual example. If a feature ignores your custom endpoint, that is Cursor's design, not a gateway failure.
- Cursor validates the configuration with a real test request when you click verify, so a wrong base URL fails immediately rather than silently.
What You Need First
Three things, all from the Zivv console:
- An account — register if you do not have one
- An API key from the API Keys page (starts with
sk-) - A model ID copied from Model Hub, for example
claude-sonnet-5orgpt-5.5
Name the key something like "Cursor - Work Laptop" so its usage is identifiable and you can revoke it without touching your other tools.
Configure Cursor
- Open Cursor Settings and go to the Models section
- Find the OpenAI API Key field and paste your
sk-key - Enable the override for the OpenAI base URL
- Enter the base URL exactly as:
https://zivv.pro/v1 - Click verify
The base URL stops at /v1. Do not append /chat/completions — Cursor adds the operation path itself, and a doubled path is the single most common cause of an immediate verification failure.
Add the Models You Actually Use
Cursor's model list mixes its built-in entries with custom ones. Add the models you plan to call through the gateway by their exact API IDs:
claude-sonnet-5— the default choice for coding and refactorsgpt-5.5— general work and OpenAI-style tool workflowsgemini-3.5-flash— cheap first drafts, summaries, and bulk edits
The name must match the id the API returns, character for character. A model called claude-sonnet-5 will not respond to claude-5-sonnet or Claude Sonnet 5. Model catalogs change over time, so copy current IDs from Model Hub rather than typing from memory. It also helps to disable built-in model entries you cannot reach through your key, so a stray dropdown selection does not produce confusing errors mid-task.
Verify Outside Cursor First
When verification fails, test the same key and URL with curl before changing anything in Cursor. First, list models:
curl https://zivv.pro/v1/models \
-H "Authorization: Bearer sk-your-key-here"Then send a minimal completion:
curl https://zivv.pro/v1/chat/completions \
-H "Authorization: Bearer sk-your-key-here" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"messages": [{"role": "user", "content": "Reply OK"}]
}'If curl succeeds and Cursor still fails, the problem is inside Cursor's settings — usually whitespace pasted with the key or a stale value that needs a restart. If curl fails too, fix the key or model first.
Common Pitfalls
| Symptom | Cause | Fix |
|---|---|---|
| Verification fails instantly | Base URL missing /v1, or includes /chat/completions | Set exactly https://zivv.pro/v1 |
| 401 Unauthorized | Truncated key, extra spaces, or a revoked key | Re-copy the full sk- key; check it with curl |
| 404 model not found | Model name does not match the API id | Copy the exact ID from Model Hub |
| Chat works, one feature does not | That feature is pinned to Cursor's own models | Expected behavior with custom keys |
| curl works, Cursor does not | Stale settings or pasted whitespace | Re-enter values and restart Cursor |
For deeper debugging of the first two rows, the 401 troubleshooting guide and the 404 model guide walk through each check in order.
Picking a Model per Task
Routing everything to the most capable model is the most common source of surprise bills. A practical split:
| Task | Model tier |
|---|---|
| Multi-file refactors, tricky bugs | claude-sonnet-5 or a current Opus model |
| Everyday edits and explanations | gpt-5.5 or gpt-5.4 |
| Summaries, boilerplate, bulk renames | gemini-3.5-flash |
Because the gateway exposes all of these behind one key, switching is a dropdown change in Cursor, not a new account.
FAQ
Does Cursor need a separate key per model? No. One Zivv key covers every model your key's group permits. You select the model per conversation inside Cursor.
Why does my model list show entries that fail? Cursor keeps built-in entries that route to official providers. With a custom base URL, only models available through your gateway key will respond. Disable the rest.
Can I use an Anthropic or Gemini protocol endpoint in Cursor? Cursor's custom key support is OpenAI-protocol only. The gateway handles the translation: you call https://zivv.pro/v1 with an OpenAI-style request and can still reach Claude and Gemini models.
Is my code sent to the gateway? Yes — whatever context Cursor includes in a request transits the endpoint you configure, same as with any API provider. Use separate keys per machine, and see the AI gateway explainer for how to evaluate a provider before trusting it.
Wrap-Up
Two values do all the work: base URL https://zivv.pro/v1 and an sk- key, plus model IDs copied exactly. If you hit an error, curl the endpoint directly and the failing layer identifies itself. Create a key and try it in Cursor in a few minutes — get started here, or see how other coding tools connect on the vibe coding page.