List models via the Cloud Agents API

Discover which model ids you can pass to Create An Agent with GET https://api.cursor.com/v1/models. Official reference: Cloud Agents API → List Models.

The Cloud Agents API v1 is in public beta. Authenticate with Basic auth (API key as username, empty password) or Authorization: Bearer YOUR_API_KEY. Create a user key at Cursor Dashboard → API Keys, or use a service account key. Availability: Beta (all plans) per the API overview.

To use the configured default model on create, omit model from the request body. Cursor resolves your user default, then your team default, then a system default.

Request

curl --request GET \
  --url https://api.cursor.com/v1/models \
  -u YOUR_API_KEY:

Response fields

Each item in items describes one model:

Field	Meaning
id	Pass this as model.id on Create An Agent.
displayName	Human-readable name in the Cursor UI.
description	Optional short description.
aliases	Optional alternate ids that resolve to the same model (for example composer-latest).
parameters	Optional per-model parameter definitions. Each has an id, optional displayName, and a values array of permitted { value, displayName? } entries. Use these to fill model.params on create.
variants	Optional concrete id + params combinations. Each has a params array (may be empty), displayName, optional description, and optional isDefault.

Example response:

{
  "items": [
    {
      "id": "composer-2",
      "displayName": "Composer 2",
      "aliases": ["composer-latest", "composer"],
      "parameters": [
        {
          "id": "fast",
          "displayName": "Fast",
          "values": [
            { "value": "false" },
            { "value": "true", "displayName": "Fast" }
          ]
        }
      ],
      "variants": [
        {
          "params": [{ "id": "fast", "value": "true" }],
          "displayName": "Composer 2",
          "isDefault": true
        },
        {
          "params": [{ "id": "fast", "value": "false" }],
          "displayName": "Composer 2"
        }
      ]
    }
  ]
}

Only use model.params ids and values that appear for the selected model. Model parameters use the same model.params shape as the TypeScript SDK ModelSelection.