Set model access configuration with the Admin API

Teams with model access control can read and update the team baseline policy over GET / PUT https://api.cursor.com/teams/model-access/configuration. Official reference: Admin API → Model access. These routes are in preview and may change before general availability.

Authenticate with a team Admin API key (Basic auth, key as username, empty password). Reads require models:read or admin:*. Writes require models:* or admin:*. Generic read:* keys cannot call these routes. Rate limit: 20 requests per minute. Writes appear in team audit logs as team_settings events.

Availability: teams with model access control enabled. The response is the team baseline; Organization Groups can still widen access for some members, and personal API key (BYOK) controls stay in the dashboard.

Read the current configuration

curl -X GET https://api.cursor.com/teams/model-access/configuration \
  -u YOUR_API_KEY:

Example response (unrestricted team):

{
  "teamId": 7,
  "state": "unrestricted",
  "newProviderDefault": null,
  "newModelDefault": null
}

Field	Meaning
teamId	Integer team ID implied by the API key
state	unrestricted, custom, or legacy
newProviderDefault	enabled or disabled when state is custom; otherwise null
newModelDefault	enabled or disabled when state is custom; otherwise null

Create or update a custom policy

Send newProviderDefault and newModelDefault (backward-compatible shorthand for state: "custom"). The first defaults PUT on an unrestricted team creates a custom policy and seeds catalog entries. Later defaults PUTs update defaults only and leave existing provider/model toggles in place.

curl -X PUT https://api.cursor.com/teams/model-access/configuration \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "newProviderDefault": "disabled",
    "newModelDefault": "enabled"
  }'

Response:

{
  "teamId": 7,
  "state": "custom",
  "newProviderDefault": "disabled",
  "newModelDefault": "enabled"
}

Field	Rules
newProviderDefault	enabled or disabled; required when creating or updating a custom policy
newModelDefault	enabled or disabled; required when creating or updating a custom policy
state	Optional; omit when sending defaults

Provider and model reads/writes return 409 while state is unrestricted or legacy. Seed configuration first, then use List model access providers and Enable or disable a model access provider.

Return the team to unrestricted

PUT with { "state": "unrestricted" } clears the custom policy (and legacy allowed/blocked lists) so state becomes unrestricted again. Defaults become null.

curl -X PUT https://api.cursor.com/teams/model-access/configuration \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{ "state": "unrestricted" }'

Response:

{
  "teamId": 7,
  "state": "unrestricted",
  "newProviderDefault": null,
  "newModelDefault": null
}

Omit newProviderDefault / newModelDefault when clearing with state: "unrestricted".

Pitfalls

• Calling with a generic read:* key — model-access routes need models:read / models:* or admin:*.
• Hitting provider or model endpoints before the first configuration PUT — expect 409 while state is unrestricted or legacy.
• Assuming a later defaults PUT resets toggles — it updates defaults only; existing provider/model flags stay as set.
• Building automation against preview paths without pinning docs — paths, fields, and errors can shift before GA.