Configuring a custom API in Cursor, and the four errors you will hit

One thing to settle before configuring

Cursor's custom API capability covers only part of the product. Tab completion and some indexing features depend on the official service, and a custom API usually applies only to the Chat and Agent panels.

That premise matters. If you configure a custom API and notice that Tab completion is not using your key, that is by design, not a failed configuration.

Setup steps

Step one: turn off the official switches that can interfere

In settings, disable or ignore the built-in official model switches. On some versions, when both are present the official channel wins.

Step two: fill in the Base URL

The key question is whether it needs /v1.

• If the relay site's documentation says https://<domain>/v1, enter https://<domain>/v1.
• Cursor appends /chat/completions itself.
• Entering https://<domain>/v1/chat/completions doubles the path and gives you a 404.

How to check: the completed address should be https://<domain>/v1/chat/completions. If you are unsure, curl that address first and confirm it responds.

Step three: fill in the API key

Watch the prefix. Some relay sites want a Bearer prefix on the key, and some Cursor versions add one themselves — doubling up produces Bearer Bearer xxx and a 401.

How to check: verify with curl first. If -H "Authorization: Bearer $KEY" works, the key itself is fine and all that remains is finding the right form in Cursor.

Step four: add the model name by hand ★ the most commonly missed step

This is the most frequent cause of "everything looks right but the model list is empty": Cursor does not pull the model list from the relay's /v1/models. You must type the model name yourself.

The name you type must be one the relay's endpoint recognises. How to check:

curl -s https://<domain>/v1/models -H "Authorization: Bearer $KEY" \
  | python -c "import sys,json;print([m['id'] for m in json.load(sys.stdin)['data']][:40])"

Use names from that list. Do not use names from official documentation, because the two frequently disagree.

Step five: deal with the verify toggle

Some versions carry a "verify" switch that fires a validation request at the official endpoint, which fails in a relay scenario.

Symptom: the configuration looks correct but you keep seeing verification failures or rejected requests. Turn it off.

The four common errors, one by one

Error one: 401 Unauthorized

Three possibilities, in order of likelihood:

1. Duplicated key prefix (Bearer Bearer) — see step three.
2. The key is disabled or out of credit on the relay — verify separately with curl.
3. The relay wants x-api-key rather than Authorization — a handful of Anthropic-protocol-only sites behave this way. Cursor speaks OpenAI format, so those sites cannot be used.

Error two: 404 Not Found

Two possibilities:

1. Base URL path duplication, where /v1/chat/completions is appended twice.
2. The relay does not recognise the model name. Some sites return 404 rather than 400 for unknown models, which is easy to misread as a path problem.

How to tell them apart: look at the error response body. A path problem usually produces an nginx HTML 404 page. A model problem usually produces a JSON error object.

Error three: 400 Bad Request

The three most common:

1. The request carries parameters the relay does not support. Cursor sends a few official extension fields, top_k or a particular tool_choice shape among them. Most sites ignore unknown fields, but strict implementations return 400 outright. For Claude-family clients there is a well-known workaround: use the site's "Cursor-specific" endpoint or a parameter-compatibility mode, which some relays provide.
2. Message structure does not match expectations. Cursor sends its own system prompt, and it is long. If the site enforces a prompt length or a content filter, the request is rejected.
3. Too many tool definitions. Cursor's Agent mode ships a large set of tool definitions, which can exceed some implementations' parsing limits.

Error four: spins forever and never returns

Cause: an incomplete streaming response, or excessive time to first token.

1. The relay buffers the request, collecting everything before forwarding, so time to first token is enormous.
2. The streaming end marker is missing, so Cursor keeps waiting.
3. The site's timeout is shorter than Cursor's patience, so the connection is cut without an error.

How to investigate: capture the stream with curl -N and look at time to first token and the end marker. See our article on the six streaming failures on relay sites; three of the six present as a spinner.

A verification checklist once configured

1. Send a simple greeting in the Chat panel → you get a reply.
2. Ask it to read a file → the tool call works. This is the critical step; see the tool use article.
3. Ask it to edit a file → the change lands correctly.
4. Continue a long conversation for several turns → no amnesia.
5. Have it output some non-ASCII prose → no mojibake.

Only when all five pass is it genuinely configured. Steps 2 and 3 are the core of the agent use case, and many people test only step 1 and assume success.

One pragmatic fallback

If you cannot get Cursor's Agent features working against a relay site, there are two ways back:

1. Switch to a relay site whose detail page marks it as Cursor-compatible. Our listings carry client compatibility notes.
2. Run a protocol conversion proxy locally, turning OpenAI format into whatever Cursor needs, and point Cursor at localhost.

The second option adds maintenance cost, but if your upstream only works in OpenAI format it is the only road.