Set model access configuration with the Organization API

Create or update a custom model-access policy (or return teams to unrestricted) for one linked team with PUT https://api.cursor.com/organizations/teams/{teamId}/model-access/configuration, or for many teams with PUT https://api.cursor.com/organizations/teams/model-access/configuration. Official reference: Organization API → Model access. These routes are in preview and may change before general availability.

Authenticate with an Organization API key (Basic auth, key as username, empty password). Writes need models:* (or admin:*). Rate limit: 20 requests per minute. Writes appear in team audit logs as team_settings events. Enterprise organizations; target teams must have model access control available.

Configuration comes first. Provider and model reads/writes return 409 while a team is still unrestricted or legacy. The first defaults PUT seeds catalog defaults; it does not clone another team’s on/off map. Enabling a model without parameter settings leaves catalog defaults — set per-model parameters on the model routes when Fast or reasoning defaults do not match org policy.

Update one team

Seed or update custom policy defaults:

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

Return one team to unrestricted:

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

Field	Rules
newProviderDefault	enabled or disabled. Required when creating or updating a custom policy; omit when state is unrestricted
newModelDefault	enabled or disabled. Required when creating or updating a custom policy; omit when state is unrestricted
state	Optional. Use unrestricted to clear policy. Omit when sending defaults

Unknown or unlinked teamId returns 404. Teams without model access control available return 403.

Bulk update many teams

Up to 100 teamIds per request. HTTP 200 means the batch was processed, not that every row succeeded — inspect errorCount and each results[].status. Successful rows are not rolled back. Operations are idempotent per team, so retry only failed teamIds. A 4xx or 5xx rejects the whole request and applies no changes. Response shape matches team-membership sync.

Seed custom policy defaults on many teams:

curl -X PUT https://api.cursor.com/organizations/teams/model-access/configuration \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "teamIds": [7, 8, 9],
    "newProviderDefault": "disabled",
    "newModelDefault": "enabled"
  }'

Return many teams to unrestricted:

curl -X PUT https://api.cursor.com/organizations/teams/model-access/configuration \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "teamIds": [7, 8, 9],
    "state": "unrestricted"
  }'

Example response:

{
  "results": [
    { "teamId": 7, "status": "success" },
    { "teamId": 8, "status": "success" },
    {
      "teamId": 9,
      "status": "error",
      "errorMessage": "Team is not linked to this organization"
    }
  ],
  "successCount": 2,
  "errorCount": 1
}

Pitfalls

• Hitting provider or model endpoints before the first configuration PUT — expect 409 while state is unrestricted or legacy.
• Treating bulk HTTP 200 as all-success — always read errorCount and per-row status.
• Assuming a later defaults PUT resets toggles — it updates defaults only; existing provider/model flags stay as set.
• Calling with members:* or usage:* alone — model-access writes need models:* or admin:*.
• Building automation against preview paths without pinning docs — paths, fields, and errors can shift before GA.

After configuration is custom, list providers on each team and toggle providers/models (including per-model parameters) with the Organization API model-access provider and model routes on the same official page. For single-team Admin API equivalents, see Set model access configuration with the Admin API.