diff --git a/docs/my-website/docs/pass_through/cursor.md b/docs/my-website/docs/pass_through/cursor.md new file mode 100644 index 00000000000..2fa460dda86 --- /dev/null +++ b/docs/my-website/docs/pass_through/cursor.md @@ -0,0 +1,260 @@ +import Image from '@theme/IdealImage'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Cursor Cloud Agents + +Pass-through endpoints for the [Cursor Cloud Agents API](https://docs.cursor.com/account/api) — launch and manage cloud agents that work on your repositories, in native format (no translation). + +| Feature | Supported | Notes | +|---------|-----------|-------| +| Cost Tracking | ✅ | Logged as $0.00 (subscription-based, no per-request pricing) | +| Logging | ✅ | All requests logged with operation classification | +| End-user Tracking | ❌ | [Tell us if you need this](https://github.com/BerriAI/litellm/issues/new) | +| Streaming | ❌ | Cursor API does not use streaming | + +Just replace `https://api.cursor.com` with `LITELLM_PROXY_BASE_URL/cursor` 🚀 + +**Supported endpoints:** + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/v0/agents` | GET | List agents | +| `/v0/agents` | POST | Launch an agent | +| `/v0/agents/{id}` | GET | Agent status | +| `/v0/agents/{id}` | DELETE | Delete an agent | +| `/v0/agents/{id}/conversation` | GET | Agent conversation | +| `/v0/agents/{id}/followup` | POST | Add follow-up | +| `/v0/agents/{id}/stop` | POST | Stop an agent | +| `/v0/me` | GET | API key info | +| `/v0/models` | GET | List models | +| `/v0/repositories` | GET | List GitHub repositories | + +## Quick Start + +### 1. Add Cursor API Key on the UI + +Navigate to **Models + Endpoints → LLM Credentials** and click **Add Credential**. Select **Cursor** from the provider dropdown — you'll see the Cursor logo. Enter your API key from [cursor.com/settings](https://cursor.com/settings). + +Add Cursor credential with logo + +### 2. Start LiteLLM Proxy + + + + +```bash +export CURSOR_API_KEY="crsr_..." + +litellm + +# RUNNING on http://0.0.0.0:4000 +``` + + + + +```yaml +model_list: + - model_name: cursor-agents + litellm_params: + model: cursor/claude-4-sonnet + api_key: os.environ/CURSOR_API_KEY + +general_settings: + master_key: sk-1234 +``` + +```bash +litellm --config config.yaml +``` + + + + +### 3. Launch a Cursor Agent + +```bash +curl -X POST http://0.0.0.0:4000/cursor/v0/agents \ + -H "Authorization: Bearer sk-1234" \ + -H "Content-Type: application/json" \ + -d '{ + "prompt": { + "text": "Add a README.md with installation instructions" + }, + "source": { + "repository": "https://github.com/your-org/your-repo", + "ref": "main" + }, + "target": { + "autoCreatePr": true + } + }' +``` + +**Expected Response:** + +```json +{ + "id": "bc_abc123", + "name": "Add README Documentation", + "status": "CREATING", + "source": { + "repository": "https://github.com/your-org/your-repo", + "ref": "main" + }, + "target": { + "branchName": "cursor/add-readme-1234", + "url": "https://cursor.com/agents?id=bc_abc123", + "autoCreatePr": true + }, + "createdAt": "2024-01-15T10:30:00Z" +} +``` + +### 4. View Logs + +Navigate to **Logs** in the sidebar. Filter by "cursor" to see your agent requests. Each request shows the operation type (e.g., `cursor/cursor:agent:create`), status, duration, and cost. + +Cursor requests in Logs page + +Click on any log entry to see full request details including provider, API base, and metadata. + +Cursor log entry detail + +## Examples + +Anything after `http://0.0.0.0:4000/cursor` is treated as a provider-specific route, and handled accordingly. + +| **Original Endpoint** | **Replace With** | +|---|---| +| `https://api.cursor.com` | `http://0.0.0.0:4000/cursor` (LITELLM_PROXY_BASE_URL) | +| `-u YOUR_API_KEY:` (Basic Auth) | `-H "Authorization: Bearer sk-1234"` (LiteLLM Virtual Key) | + +### List Available Models + +```bash +curl http://0.0.0.0:4000/cursor/v0/models \ + -H "Authorization: Bearer sk-1234" +``` + +```json +{ + "models": [ + "claude-4-sonnet-thinking", + "gpt-5.2", + "claude-4.5-sonnet-thinking" + ] +} +``` + +### Check Agent Status + +```bash +curl http://0.0.0.0:4000/cursor/v0/agents/bc_abc123 \ + -H "Authorization: Bearer sk-1234" +``` + +### List All Agents + +```bash +curl http://0.0.0.0:4000/cursor/v0/agents \ + -H "Authorization: Bearer sk-1234" +``` + +### Add Follow-up to Agent + +```bash +curl -X POST http://0.0.0.0:4000/cursor/v0/agents/bc_abc123/followup \ + -H "Authorization: Bearer sk-1234" \ + -H "Content-Type: application/json" \ + -d '{ + "prompt": { + "text": "Also add a section about troubleshooting" + } + }' +``` + +### Stop an Agent + +```bash +curl -X POST http://0.0.0.0:4000/cursor/v0/agents/bc_abc123/stop \ + -H "Authorization: Bearer sk-1234" +``` + +### Delete an Agent + +```bash +curl -X DELETE http://0.0.0.0:4000/cursor/v0/agents/bc_abc123 \ + -H "Authorization: Bearer sk-1234" +``` + +### Get API Key Info + +```bash +curl http://0.0.0.0:4000/cursor/v0/me \ + -H "Authorization: Bearer sk-1234" +``` + +```json +{ + "apiKeyName": "Production API Key", + "createdAt": "2024-01-15T10:30:00Z", + "userEmail": "developer@example.com" +} +``` + +## Advanced — Use with Virtual Keys + +Pre-requisites: +- [Setup proxy with DB](../proxy/virtual_keys.md#setup) + +Use this to avoid giving developers the raw Cursor API key, but still letting them use Cursor endpoints. + +### Usage + +1. Setup environment + +```bash +export DATABASE_URL="" +export LITELLM_MASTER_KEY="" +export CURSOR_API_KEY="" +``` + +```bash +litellm + +# RUNNING on http://0.0.0.0:4000 +``` + +2. Generate virtual key + +```bash +curl -X POST 'http://0.0.0.0:4000/key/generate' \ + -H 'Authorization: Bearer sk-1234' \ + -H 'Content-Type: application/json' \ + -d '{}' +``` + +3. Launch an agent using the virtual key + +```bash +curl -X POST http://0.0.0.0:4000/cursor/v0/agents \ + -H "Authorization: Bearer sk-1234ewknldferwedojwojw" \ + -H "Content-Type: application/json" \ + -d '{ + "prompt": { + "text": "Fix the failing test in test_utils.py" + }, + "source": { + "repository": "https://github.com/your-org/your-repo", + "ref": "main" + } + }' +``` + +## Related + +- [Cursor Cloud Agents API Docs](https://docs.cursor.com/account/api) +- [Pass-through Endpoints Overview](./intro.md) +- [Virtual Keys](../proxy/virtual_keys.md) diff --git a/docs/my-website/img/cursor_add_credential.png b/docs/my-website/img/cursor_add_credential.png new file mode 100644 index 00000000000..5b0eb1ffe51 Binary files /dev/null and b/docs/my-website/img/cursor_add_credential.png differ diff --git a/docs/my-website/img/cursor_log_detail.png b/docs/my-website/img/cursor_log_detail.png new file mode 100644 index 00000000000..5fdb1dd4a1c Binary files /dev/null and b/docs/my-website/img/cursor_log_detail.png differ diff --git a/docs/my-website/img/cursor_logs.png b/docs/my-website/img/cursor_logs.png new file mode 100644 index 00000000000..ab5aeafc772 Binary files /dev/null and b/docs/my-website/img/cursor_logs.png differ diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index b01bb53cfe7..60325d0efc7 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -635,6 +635,7 @@ const sidebars = { "pass_through/bedrock", "pass_through/azure_passthrough", "pass_through/cohere", + "pass_through/cursor", "pass_through/google_ai_studio", "pass_through/langfuse", "pass_through/mistral", diff --git a/ui/litellm-dashboard/public/assets/logos/cursor.svg b/ui/litellm-dashboard/public/assets/logos/cursor.svg index a45cefbefe5..79b44c5e83b 100644 --- a/ui/litellm-dashboard/public/assets/logos/cursor.svg +++ b/ui/litellm-dashboard/public/assets/logos/cursor.svg @@ -1,5 +1 @@ - - - - - +Cursor