Cursor

Cursor supports custom API keys, an OpenAI base URL override, and custom model names for standard chat models. Configure these settings to send Cursor Ask mode requests through AISIX.

In this guide, you will configure Cursor with an AISIX caller API key and use an AISIX model alias as the custom model name. AISIX then authenticates the caller, applies gateway policies, and forwards requests to the upstream model configured for the alias.

info

This configuration applies to Ask mode. Agent mode, nested agents, background agents, Tab Completion, inline edits, and other features that use Cursor's specialized models follow Cursor-managed paths instead of the AISIX base URL.

Prerequisites

Before starting, prepare the following:

• Cursor Pro or a higher plan. The free plan saves the API key, base URL, and custom model, but requires an upgrade before the custom model can be selected in Chat.
• A running AISIX gateway with a proxy URL that Cursor can reach.
• An AISIX caller API key.
• A model alias the caller API key can access through the OpenAI-Compatible API.

Confirm that AISIX exposes the alias before configuring Cursor:

curl -sS "https://aisix.example.com/v1/models" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY"

Configure Cursor

1. Open Cursor Settings and select Models.

2. In the OpenAI API Key field, enter your AISIX caller API key.

3. In Override OpenAI Base URL, enter the AISIX proxy API root, including /v1. For example:

   https://aisix.example.com/v1

4. In Add or search model, enter the AISIX model alias and press Enter. For example, enter aisix_cursor.

5. Enable the custom model.

6. Open Cursor Chat, select Ask mode, and select the custom model.

Use a neutral model alias that does not contain or resemble a provider model ID. For example, use aisix_cursor rather than gpt-4o-prod. Cursor can otherwise interpret the alias as a built-in model and route or format the request differently. The custom model name sent by Cursor must match the AISIX model alias, not the upstream provider's model name.

The resulting configuration maps Cursor settings to AISIX as follows:

Cursor setting	AISIX value
OpenAI API Key	AISIX caller API key
Override OpenAI Base URL	AISIX proxy URL with /v1
Custom model	AISIX model alias

Verify the Integration

Open Ask mode with Cmd+L on macOS or Ctrl+L on Windows and Linux. Select the custom model, then send a short prompt. For example, ask the model to respond with a specific word or short phrase.

When the request succeeds, verify the following results:

• Cursor Chat displays the expected response.
• AISIX records a successful POST /v1/chat/completions request.
• The AISIX request record identifies the expected caller API key and model alias.

AISIX resolves the alias to the configured upstream provider and model. Cursor does not need the upstream provider credential or upstream model name.

Troubleshoot Cursor Requests

If the request fails, check these items:

Symptom	Check
Cursor prompts you to upgrade when you open the model selector	Confirm that you are using Cursor Pro or a higher plan. The free plan saves the configuration but does not let you select the custom model.
Authentication fails	Confirm the value in OpenAI API Key is an AISIX caller API key, not the upstream provider key.
Model is not found	Confirm the custom model name exactly matches an AISIX model alias available to the caller.
Cursor reports a connection or endpoint error	Confirm the base URL is reachable from Cursor, uses HTTPS when required by your environment, and ends in /v1.
Requests use an unexpected model or payload	Use a neutral alias that does not contain a provider model ID, then explicitly select it in Ask mode.
Built-in models return errors	Clear Override OpenAI Base URL when switching back to built-in models. The override applies globally to OpenAI-compatible requests.
Requests do not appear in AISIX logs	Confirm Override OpenAI Base URL is configured and the custom model is selected in Ask mode. Agent mode, Tab Completion, and other specialized features do not use this path.

Next Steps

• OpenAI-Compatible API: review the gateway-facing request format.
• Metrics and Logs: confirm gateway-side request metrics and logs.
• Rate Limits: add caller or model limits for Cursor chat traffic.
• Cursor API Keys: review which Cursor models and features support custom API keys.