> [!WARNING]
>
> **Preview**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

Gemini Notebook Enterprise is a powerful tool for generating insights and
summaries from your documents. This page describes the APIs that let you
perform the following notebook management tasks programmatically:

- [Create a notebook](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks.md.txt#create-notebook)
- [Retrieve a notebook](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks.md.txt#get-notebook)
- [List recently viewed notebooks](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks.md.txt#list-notebook)
- [Delete a notebook](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks.md.txt#delete-notebook)
- [Share a notebook](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks.md.txt#share-notebook)

## Before you begin

Before you start working with your notebooks, do the following:

- [Set up Gemini Notebook Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/set-up-notebooklm.md.txt).
- [Get licenses for Gemini Notebook Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/set-up-licensing.md.txt) and assign a license to your user account.
- [Grant the Cloud NotebookLM User role](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/set-up-notebooklm.md.txt#grant-roles) (`roles/discoveryengine.notebookLmUser`) to your user account.
- In a local terminal or [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), sign in to the
  [Google Cloud CLI](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt) with your user credentials by running
  the [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) command:

  ```bash
  gcloud auth login
  ```

  Signing in with your user credentials ensures that
  `gcloud auth print-access-token` generates an access token for your user
  account. The [`projects.locations.notebooks` REST
  API](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.notebooks) methods on
  this page require an authenticated user account with an active
  Gemini Notebook Enterprise license.

## Use the US multi-regional endpoint

If your Gemini Notebook Enterprise subscription is in the US
multi-region, you can send the requests on this page to the US multi-regional
endpoint, `discoveryengine.us.rep.googleapis.com`. A multi-regional endpoint
processes your requests and terminates TLS within the multi-region, so your
request data stays in the US while it's in transit. Using this endpoint doesn't
change where your notebooks are stored. For more information, see
[Regional and multi-regional API endpoints
overview](https://docs.cloud.google.com/docs/security/compliance/about-regional-endpoints) in the Google Cloud
security guide.

To use the US multi-regional endpoint, make the following changes to each
request URL on this page:

1. Replace the
   `ENDPOINT_LOCATION-discoveryengine.googleapis.com`
   host with `discoveryengine.us.rep.googleapis.com`.

2. Set `LOCATION` to `us`.

The rest of each request stays the same. To learn how you choose your
subscription's multi-region, see
[Get a subscription](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/set-up-licensing.md.txt#get-subscription).
For the list of regional and multi-regional service endpoints, see
[Regional and multi-regional service endpoints](https://docs.cloud.google.com/vpc/docs/regional-service-endpoints.md.txt)
in the Virtual Private Cloud guide.

## Create a notebook

To create a new notebook, use the
[`notebooks.create`](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.notebooks/create.md.txt)
method.

### REST

```bash
curl -X POST \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks" \
  -d '{
  "title": "NOTEBOOK_TITLE",
  }'
```

Replace the following:

- `ENDPOINT_LOCATION`: the multi-region for your API request. Specify one of the following values:
  - `us` for the US multi-region
  - `eu` for the EU multi-region
  - `global` for the Global location

  For more information, see [Specify a multi-region
  for your data store](https://docs.cloud.google.com/gemini/enterprise/docs/locations#specify_a_multi-region_for_your_data_store).
- `PROJECT_NUMBER`: the number of your Google Cloud project.
- `LOCATION`: the geographic location of your data store, such as `global`. For more information, see [Locations](https://docs.cloud.google.com/gemini/enterprise/docs/locations.md.txt).
- `NOTEBOOK_TITLE`: a UTF-8 encoded string used as a title for the notebook that you want to create.

If the request is successful, you should receive a JSON similar to the
following.

```json
{
"title": "NOTEBOOK_TITLE",
"notebookId": "NOTEBOOK_ID",
"emoji": "",
"metadata": {
  "userRole": "PROJECT_ROLE_OWNER",
  "isShared": false,
  "isShareable": true
},
"name": "NOTEBOOK_NAME"
}
```

Note the following:

- `NOTEBOOK_ID`: a unique ID to identify the created notebook. You need the notebook ID for other notebook management tasks, such as sharing or retrieving.
- `NOTEBOOK_NAME`: the complete resource name of the notebook. This field has the following pattern: `projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID
  `

### Access the created notebook and get its ID in a browser

To access the created notebook and get its ID using a browser, do the following.

1. Go to the Gemini Notebook Enterprise homepage that's available at one of
   the following URLs:

   1. If you're using a Google identity, go to:

          https://notebook.cloud.google.com/LOCATION/?project=PROJECT_NUMBER

   2. If you're using a third-party identity, go to:

          https://notebook.cloud.google/LOCATION/?project=PROJECT_NUMBER

2. Select the created notebook. The URL of the selected notebook has the following pattern:

   1. If you're using a Google identity:

          https://notebook.cloud.google.com/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER

   2. If you're using a third-party identity:

          https://notebook.cloud.google/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER

3. Note the URL and the notebook ID, which are useful for other notebook
   management tasks, such as sharing.

## Retrieve a notebook

To retrieve a specific notebook using its notebook ID, use the
[`notebooks.get`](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.notebooks/get.md.txt)
method.

### REST

```bash
curl -X GET \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID"
```

Replace the following:

- `ENDPOINT_LOCATION`: the multi-region for your API request. Specify one of the following values:
  - `us` for the US multi-region
  - `eu` for the EU multi-region
  - `global` for the Global location

  For more information, see [Specify a multi-region
  for your data store](https://docs.cloud.google.com/gemini/enterprise/docs/locations#specify_a_multi-region_for_your_data_store).
- `PROJECT_NUMBER`: the number of your Google Cloud project.
- `LOCATION`: the geographic location of your data store, such as `global`. For more information, see [Locations](https://docs.cloud.google.com/gemini/enterprise/docs/locations.md.txt).
- `NOTEBOOK_ID`: the notebook's unique identifier that you received when you created the notebook.

If the request is successful, you should get a JSON response similar to the
following for an empty notebook. If you call this method after you
[add sources](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks-sources.md.txt#add-source-notebook) to your notebook, you
receive details about all the sources added to the retrieved notebook. If you
have [configured CMEK
details](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/cmek),
you also receive CMEK-related information for the notebook.

```json
{
"title": "NOTEBOOK_TITLE",
"notebookId": "NOTEBOOK_ID",
"emoji": "",
"metadata": {
  "userRole": "PROJECT_ROLE_OWNER",
  "isShared": false,
  "isShareable": true,
  "lastViewed": "LAST_VIEWED_TIME",
  "createTime": "LAST_CREATED_TIME"
},
"name": "NOTEBOOK_NAME"
}
```

## List recently viewed notebooks

To get a list of all notebooks in a project that were recently viewed, use the
[`notebooks.listRecentlyViewed`](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.notebooks/listRecentlyViewed.md.txt)
method. By default, the response lists the last 500 notebooks. You can choose
to paginate the responses with the `pageSize` query parameter.

### REST

```bash
curl -X GET \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks:listRecentlyViewed"
```

Replace the following:

- `ENDPOINT_LOCATION`: the multi-region for your API request. Specify one of the following values:
  - `us` for the US multi-region
  - `eu` for the EU multi-region
  - `global` for the Global location

  For more information, see [Specify a multi-region
  for your data store](https://docs.cloud.google.com/gemini/enterprise/docs/locations#specify_a_multi-region_for_your_data_store).
- `PROJECT_NUMBER`: the number of your Google Cloud project.
- `LOCATION`: the geographic location of your data store, such as `global`. For more information, see [Locations](https://docs.cloud.google.com/gemini/enterprise/docs/locations.md.txt).

If the request is successful, you should get a JSON response similar to the
following. The response contains up to last 500 notebooks that a user
accessed recently.

```json
{
  "notebooks": [
    {
      "title": "NOTEBOOK_TITLE_1",
      "notebookId": "NOTEBOOK_ID_1",
      "emoji": "",
      "metadata": {
        "userRole": "PROJECT_ROLE_OWNER",
        "isShared": false,
        "isShareable": true,
        "lastViewed": "LAST_VIEWED_TIME",
        "createTime": "LAST_CREATED_TIME"
      },
      "name": "NOTEBOOK_NAME_1"
    },
    {
      "title": "NOTEBOOK_TITLE_2",
      "notebookId": "NOTEBOOK_ID_2",
      "emoji": "",
      "metadata": {
        "userRole": "PROJECT_ROLE_OWNER",
        "isShared": false,
        "isShareable": true,
        "lastViewed": "LAST_VIEWED_TIME",
        "createTime": "LAST_CREATED_TIME"
      },
      "name": "NOTEBOOK_NAME_2"
    }
  ]
}
```

## Delete a notebook

To delete a notebook, use the
[`notebooks.batchDelete`](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.notebooks/batchDelete.md.txt)
method.

### REST

```bash
curl -X POST \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks:batchDelete" \
  -d '{
    "names": [
      "NOTEBOOK_NAME"
    ]
  }'
```

Replace the following:

- `ENDPOINT_LOCATION`: the multi-region for your API request. Specify one of the following values:
  - `us` for the US multi-region
  - `eu` for the EU multi-region
  - `global` for the Global location

  For more information, see [Specify a multi-region
  for your data store](https://docs.cloud.google.com/gemini/enterprise/docs/locations#specify_a_multi-region_for_your_data_store).
- `PROJECT_NUMBER`: the number of your Google Cloud project.
- `LOCATION`: the geographic location of your data store, such as `global`. For more information, see [Locations](https://docs.cloud.google.com/gemini/enterprise/docs/locations.md.txt).
- `NOTEBOOK_NAME`: the complete resource name of the
  notebook to be deleted. This field has the pattern:
  `projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID`.

  If the request is successful, you receive an empty JSON object. If the
  notebook doesn't exist, you also receive an empty JSON object, so make
  sure to specify the notebook name correctly.

## Share a notebook

To share a new notebook, use the
[`notebooks.share`](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.notebooks/share.md.txt)
method.

The user with whom you want to share the notebook must be granted the
[Cloud NotebookLM User](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/overview.md.txt#user_roles) role.

### REST

1. In your Google Cloud project, assign the `Cloud NotebookLM User`
   Identity and Access Management (IAM) role to the users with whom you want to share the
   notebook.

2. Call the following method.

   ```bash
   curl -X POST \
     -H "Authorization:Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID:share" \
     -d '{
       "accountAndRoles": [
        {
           "email":"USER_EMAIL_1",
           "role":"USER_ROLE_1",
        },
        {
           "email":"USER_EMAIL_2",
           "role":"USER_ROLE_2",
        },
       ]
     }'
   ```

   Replace the following:
   - `ENDPOINT_LOCATION`: the multi-region for your API request. Specify one of the following values:
     - `us` for the US multi-region
     - `eu` for the EU multi-region
     - `global` for the Global location

     For more information, see [Specify a multi-region
     for your data store](https://docs.cloud.google.com/gemini/enterprise/docs/locations#specify_a_multi-region_for_your_data_store).
   - `PROJECT_NUMBER`: the number of your Google Cloud project.
   - `LOCATION`: the geographic location of your data store, such as `global`. For more information, see [Locations](https://docs.cloud.google.com/gemini/enterprise/docs/locations.md.txt).
   - `NOTEBOOK_ID`: a unique ID to identify the notebook that you want to share. You need the notebook ID for other notebook management tasks, such as sharing or retrieving.
   - `USER_EMAIL`: the email address of the user with whom you want to share the notebook.
   - `USER_ROLE`: a role that you want to assign to
     the user. It can be one of the following:

     - `PROJECT_ROLE_WRITER`: The user has write permissions on the project.
     - `PROJECT_ROLE_READER`: The user has read permissions on the project.
     - `PROJECT_ROLE_NOT_SHARED`:The user has no access to the project.

   If the request is successful, you receive an empty JSON object.

> [!NOTE]
> **Note:** You can't assign `PROJECT_ROLE_OWNER` with this method. The account that creates a notebook is its owner, and ownership can't be transferred.

### Verify users using a browser

To verify whether you've shared the notebook with the correct users and
assigned them correct roles, do the following:

1. Open the notebook in your browser. A notebook has the following URL pattern:

   1. If you're using a Google identity:

          https://notebook.cloud.google.com/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER

   2. If you're using a third-party identity:

          https://notebook.cloud.google/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER

2. Click **Share**.

3. Verify the users listed as **People with access** and their assigned roles.

## What's next

- [Add data sources of different types to your notebooks](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks-sources.md.txt) programmatically.