---
title: "Create or replace a grant setting"
method: PUT
path: "/v3/grants/{grant_id}/settings/{setting_name}"
tags: ["Manage Grants"]
---

# Create or replace a grant setting

`PUT /v3/grants/{grant_id}/settings/{setting_name}`

## Request

- Base URL: `https://api.us.nylas.com`
- URL: `https://api.us.nylas.com/v3/grants/{grant_id}/settings/{setting_name}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nylas/apis/nylas-api/docs/v3/grants/:grant_id/settings/:setting_name/put.ts> (a function with typed inputs; its response is checked against the schema)

Creates the setting, or replaces it if it already exists. Send the value under the same key as
`setting_name`. You don't need to know whether the grant already has a value, and retrying the
same request is safe. What each setting accepts is in the request body schema.

## Request body

- object
  - `synced-calendars` string[], required: The calendar IDs to sync, from 1 to 50. Nylas syncs and sends `calendar.*` and `event.*` notifications for these calendars only, starting from the grant's next sync. It checks every ID against the grant's calendars before it saves anything, so use the provider's calendar IDs from [`GET /v3/grants/{grant_id}/calendars`](/docs/reference/api/calendar/get-all-calendars/), not `primary`. To remove the list, delete the setting instead of sending an empty array.

## Response `200`

OK

- object
  - `request_id` string: The request ID.
  - `data` GrantSettingsObject: The grant's public settings. Each key is the setting name, the same as in the path. A setting that isn't set is `null`.
    - `synced-calendars` string[], nullable: The calendars that Nylas syncs and sends `calendar.*` and `event.*` notifications for on this grant, as provider calendar IDs. `null` when the grant has no list, which means the **Subscribe to primary calendars only** setting in the Dashboard applies. For how the two interact, see [Sync and notify for specific calendars](/docs/v3/calendar/#sync-and-notify-for-specific-calendars).

## Other responses

- `400`: Bad Request
- `401`: Not Authenticated
- `404`: Not Found

## Changes

- **2026-10-27** `d8ee467a1e7e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nylas/apis/nylas-api/changes/v3/grants/:grant_id/settings/:setting_name/put.md)

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) - [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nylas/apis/nylas-api/revisions/7782a3e3ab70?raw)